ETSITS 129 198-14 V6.3.1 



(2006-07) 



Technical Specification 



Universal Mobile Telecommunications System (UMTS); 

Open Service Access (OSA) 

Application Programming Interface (API); 

Part 14: Presence and Availability Management (PAM) 

Service Capability Feature (SCF) 
(3GPP TS 29.198-14 version 6.3.1 Release 6) 



3ji^ 




U 



3GPP TS 29.1 98-1 4 version 6.3.1 Release 6 1 ETSI TS 1 29 1 98-1 4 V6.3.1 (2006-07) 



Reference 



RTS/TSGC-05291 98-1 4v631 
Keywords 



UMTS 



ETSI 

650 Route des Lucioles 
F-06921 Sophia Antipolis Cedex - FRANCE 

Tel. : +33 4 92 94 42 00 Fax: +33 4 93 65 47 1 6 

Siret N ° 348 623 562 0001 7 - NAF 742 C 
Association a but non lucratif enregistree a la 
Sous-Prefecture de Grasse (06) N° 7803/88 



Important notice 



Individual copies of the present document can be downloaded from: 
http://www.etsi.orq 

The present document may be made available in more than one electronic version or in print. In any case of existing or 

perceived difference in contents between such versions, the reference version is the Portable Document Format (PDF). 

In case of dispute, the reference shall be the printing on ETSI printers of the PDF version kept on a specific network drive 

within ETSI Secretariat. 

Users of the present document should be aware that the document may be subject to revision or change of status. 

Information on the current status of this and other ETSI documents is available at 

http://portal.etsi.orq/tb/status/status.asp 

If you find errors in the present document, please send your comment to one of the following services: 

http://portal.etsi.orq/chaircor/ETSI support.asp 

Copyright Notification 

No part may be reproduced except as authorized by written permission. 
The copyright and the foregoing restriction extend to reproduction in all media. 

© European Telecommunications Standards Institute 2006. 
All rights reserved. 

DECT'^", PLUGTESTS™ and UMTS™ are Trade IVlarks of ETSI registered for the benefit of its IVIembers. 
TIPHON^" and the TIPHON logo are Trade Marks currently being registered by ETSI for the benefit of its Members. 
2QppTM |g g jracle Mark of ETSI registered for the benefit of its Members and of the 3GPP Organizational Partners. 



ETSI 



3GPP TS 29.1 98-1 4 version 6.3.1 Release 6 2 ETSI TS 1 29 1 98-1 4 V6.3.1 (2006-07) 



Intellectual Property Rights 



IPRs essential or potentially essential to the present document may have been declared to ETSI. The information 
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found 
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in 
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web 
server ( http://webapp.etsi.org/IPR/home.asp ). 

Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee 
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web 
server) which are, or may be, or may become, essential to the present document. 



Foreword 

This Technical Specification (TS) has been produced by ETSI 3rd Generation Partnership Project (3GPP). 

The present document may refer to technical specifications or reports using their 3GPP identities, UMTS identities or 
GSM identities. These should be interpreted as being references to the corresponding ETSI deliverables. 

The cross reference between GSM, UMTS, 3GPP and ETSI identities can be found under 
http://webapp.etsi.org/kev/quervform.asp . 



ETSI 



3GPP TS 29.198-14 version 6.3.1 Release 6 3 ETSI TS 129 198-14 V6.3.1 (2006-07) 



Contents 



Intellectual Property Rights 2 

Foreword 2 

Foreword 9 

Introduction 9 

1 Scope 11 

2 References 11 

3 Definitions and abbreviations 11 

3.1 Definitions 11 

3.2 Abbreviations 12 

4 Presence and Availability Management SCF 12 

4.1 Introduction 12 

4.2 Motivation 12 

4.3 Goals 12 

4.4 Concepts 12 

4.4.1 Identity 13 

4.4.2 Presence 13 

4.4.3 Availability 14 

4.4.4 Events 15 

4.5 Scope of PAM information 15 

4.6 Security and privacy 15 

5 Sequence Diagrams 16 

5.1 Use of authentication tokens 16 

5.2 Event registration and notification 17 

6 Class Diagrams 18 

6.1 PAM Provisioning SCF Class Diagrams 18 

6.2 PAM Access SCF Class Diagrams 19 

6.3 PAM Event SCF Class Diagrams 20 

7 The Service Interface Specifications 21 

7.1 Interface Specification Format 21 

7.1.1 Interface Class 21 

7.1.2 Method descriptions 21 

7.1.3 Parameter descriptions 22 

7.1.4 State Model 22 

7.2 Base Interface 22 

7.2.1 Interface Class Iplnterface 22 

7.3 Service Interfaces 22 

7.3.1 Overview 22 

7.4 Generic Service Interface 22 

7.4.1 Interface Class IpService 22 

7.4.1.1 Method setCallbackO 23 

7.4.1.2 Method setCallbackWithSessionlDQ 23 

8 Presence and Availability Management Interface Classes 23 

8.1 PAM Provisioning SCF Interface Classes 24 

8.1.1 Interface Class IpPAMProvisioningManager 24 

8.1.1.1 Method getAuthTokenO 24 

8.1.1.2 Method obtainlnterfaceQ 25 

8.1.1.3 Method «new» getAccessControlQ 25 

8.1.1.4 Method «new» setAccessControlQ 26 

8.1.2 Interface Class IpPAMIdentityManagement 26 

8.1.2.1 Method createldentityO 27 



£75/ 



3GPP TS 29.198-14 version 6.3.1 Release 6 4 ETSI TS 129 198-14 V6.3.1 (2006-07) 

8.1.2.2 Method deleteldentityO 28 

8.1.2.3 Method isIdentityO 28 

8.1.2.4 Method createGroupIdentityO 29 

8.1.2.5 Method deleteGroupIdentityO 29 

8.1.2.6 Method addToGroupO 29 

8.1.2.7 Method removeFromGroupO 30 

8.1.2.8 Method listMembersO 30 

8.1.2.9 Method isGroupIdentityO 31 

8.1.2.10 Method listGroupMembershipO 31 

8.1.2.11 Method addAliasO 32 

8.1.2.12 Method removeAUasesQ 32 

8.1.2.13 Method listAliasesO 33 

8.1.2.14 Method lookupByAliasO 33 

8.1.2.15 Method associateTypes() 33 

8.1.2.16 Method disassociateTypes() 34 

8.1.2.17 Method listTypesOfldentityO 34 

8.1.2.18 Method hasTypeO 35 

8.1.2.19 Method getldentityAttributesO 35 

8.1.2.20 Method setldentityAttributesQ 36 

8.1.3 Interface Class IpPAMAgentManagement 36 

8.1.3.1 Method createAgentO 37 

8.1.3.2 Method deleteAgentO 38 

8.1.3.3 Method isAgentO 38 

8.1.3.4 Method enableCapabilitiesQ 38 

8.1.3.5 Method disableCapabilitiesQ 39 

8.1.3.6 Method listEnabledCapabilitiesQ 39 

8.1.3.7 Method listAllCapabilitiesO 40 

8.1.3.8 Method isCapableOfO 40 

8.1.3.9 Method associateTypesQ 41 

8.1.3.10 Method disassociateTypesQ 41 

8.1.3.11 Method listTypesOfAgentO 42 

8.1.3.12 Method hasTypeO 42 

8.1.3.13 Method getAgentAttributesQ 42 

8.1.3.14 Method setAgentAttributesQ 43 

8.1.4 Interface Class IpPAMAgentAssignment 44 

8.1.4.1 Method assignAgentO 44 

8.1.4.2 Method unassignAgentO 45 

8.1.4.3 Method listAssignedAgentsQ 45 

8.1.4.4 Method listAssociatedldentitiesOfAgentQ 46 

8.1.4.5 Method listAssignedAgentsByCapabilityO 46 

8.1.4.6 Method listCapabilitiesOfldentityO 46 

8.1.4.7 Method isIdentityCapableOfO 47 

8.1.5 Interface Class IpPAMIdentityTypeManagement 47 

8.1.5.1 Method createldentityAttributeQ 48 

8.1.5.2 Method deleteldentityAttributeO 48 

8.1.5.3 Method getldentityAttributeDefinitionQ 49 

8.1.5.4 Method listAllIdentityAttributesQ 49 

8.1.5.5 Method createldentityTypeQ 49 

8.1.5.6 Method deleteldentityTypeO 50 

8.1.5.7 Method listldentityTypesQ 50 

8.1.5.8 Method addldentityTypeAttributesQ 51 

8.1.5.9 Method removeldentityTypeAttributesO 51 

8.1.5.10 Method listldentityTypeAttributesO 52 

8.1.6 Interface Class IpPAMAgentTypeManagement 52 

8.1.6.1 Method createAgentAttributeQ 53 

8.1.6.2 Method deleteAgentAttributeO 53 

8.1.6.3 Method getAgentAttributeDefinitionO 54 

8.1.6.4 Method listAllAgentAttributesQ 54 

8.1.6.5 Method createAgentTypeQ 54 

8.1.6.6 Method deleteAgentTypeO 55 

8.1.6.7 Method listAgentTypesQ 55 

8.1.6.8 Method addAgentTypeAttributesQ 56 



£75/ 



3GPP TS 29.1 98-1 4 version 6.3.1 Release 6 5 ETSI TS 1 29 1 98-1 4 V6.3.1 (2006-07) 

8.1.6.9 Method removeAgentTypeAttributesQ 56 

8.1.6.10 MethodlistAgentTypeAttributesQ 57 

8.1.7 Interface Class IpPAMCapabilityManagement 57 

8.1.7.1 Method createCapabilityAttributeQ 58 

8.1.7.2 Method deleteCapabilityAttributeO 58 

8.1.7.3 Method getCapabilityAttributeDefinitionO 59 

8.1.7.4 Method listAllCapabilityAttributesO 59 

8.1.7.5 Method createCapabilityO 60 

8.1.7.6 Method deleteCapabilityO 60 

8.1.7.7 Method listCapabilitiesQ 60 

8.1.7.8 Method addCapabilityAttributesQ 61 

8.1.7.9 Method removeCapabilityAttributesQ 61 

8.1.7.10 Method listCapabilityAttributesQ 62 

8.1.7.11 Method assignCapabilitiesToType() 62 

8.1.7.12 Method unassignCapabilitiesFromType() 63 

8.1.7.13 Method listCapabilitiesOfTypeO 63 

8.2 PAM Access SCF Interface Classes 63 

8.2.1 Interface Class IpPAMPresenceAvailabilityManager 63 

8.2.1.1 Method getAuthTokenO 64 

8.2.1.2 Method obtainlnterfaceQ 64 

8.2.1.3 Method «new» getAccessControlQ 65 

8.2.1.4 Method «new» setAccessControlQ 65 

8.2.1.5 Method «new» activateServiceQ 66 

8.2.1.6 Method «new» deactivates ervice() 66 

8.2.1.7 Method «new» isActiveldentityO 66 

8.2.2 Interface Class IpPAMIdentityPresence 67 

8.2.2.1 Method setldentityPresenceQ 67 

8.2.2.2 Method setIdentityPresenceExpiration() 68 

8.2.2.3 Method getldentityPresenceO 68 

8.2.3 Interface Class IpPAMAvailability 69 

8.2.3.1 Method getAvailabilityO 70 

8.2.3.2 Method getPreferenceO 71 

8.2.3.3 Method setPreferenceO 71 

8.2.4 Interface Class IpAppPAMPreferenceCheck 72 

8.2.4.1 Method computeAvailabilityO 72 

8.3 PAM Event SCF Interface Classes 73 

8.3.1 Interface Class IpPAMEventManager 73 

8.3.1.1 Method getAuthTokenO 73 

8.3.1.2 Method obtainlnterfaceQ 74 

8.3.1.3 Method «new» getAccessControlQ 74 

8.3.1.4 Method «new» setAccessControlQ 75 

8.3.1.5 Method «new» activateServiceQ 75 

8.3.1.6 Method «new» deactivates erviceQ 76 

8.3.1.7 Method «new» isActiveldentityQ 76 

8.3.2 Interface Class IpAppPAMEventHandler 76 

8.3.2.1 Method eventNotifyQ 77 

8.3.2.2 Method eventNotifyErrQ 77 

8.3.3 Interface Class IpPAMEventHandler 77 

8.3.3.1 Method isRegisteredQ 78 

8.3.3.2 Method registerAppInterfaceQ 78 

8.3.3.3 Method registerForEventQ 79 

8.3.3.4 Method deregisterAppInterfaceQ 79 

8.3.3.5 Method deregisterFromEventQ 80 

9 State Transition Diagrams 80 

10 PAM Service Properties 80 

10.1 PAM Access Service 81 

10.2 PAM Event Service 81 

11 PAM Data Definitions 81 

11.1 Entity Address Definitions 81 

11.1.1 TpPAMFQName 81 



£75/ 



3GPP TS 29.198-14 version 6.3.1 Release 6 6 ETSI TS 129 198-14 V6.3.1 (2006-07) 

TpPAMFQNameList 81 

Attribute Data Definitions 81 

TpPAMAttribute 81 

TpPAMAttributeList 81 

TpPAMAttributeDef 82 

TpPAMAttributeDefList 82 

Presence Data Definitions 82 

TpPAMCapability 82 

TpPAMCapabilityList 82 

TpPAMPresenceData 82 

TpPAMPresenceDataList 83 

Pre-defined Presence type 83 

Presentity 83 

Availability Data Definitions 83 

TpPAMAvailabilityProfile 83 

TpPAMAvailabilityProfileList 83 

TpPAMPrivacyCode 83 

Availability Context Data Definitions 83 

TpPAMContext 84 

TpPAMContextName 84 

TpPAMContextData 84 

TpPAMCommunicationContext 84 

TpPAMContextList 84 

Credential data definitions 85 

TpPAMCredential 85 

Availability and Access Control Preference Data Definitions 85 

IpAppPAMPreferenceCheckRef 85 

TpPAMAccessControlData 85 

TpPAMACLDefault 85 

TpPAMPreferenceOp 85 

TpPAMPreferenceType 86 

TpPAMPreferenceData 86 

Time data definitions 86 

TpPAMTimelnterval 86 

Pre-defined Entity Types and Attributes 86 

Interface name definitions 87 

TpPAMProvisioninglnterfaceName 87 

TpPAMPresenceAvailabilitylnterfaceName 87 

TpPAMEventlnterfaceName 87 

Event data definitions 88 

IpAppPAMEventHandlerRef 88 

TpPAMClientlD 88 

TpPAMEventlD 88 

TpPAMEventName 88 

TpPAMEventNameList 88 

TpPAMEventlnfo 89 

TpPAMEventlnfbList 89 

TpPAMNotificationlnfo 89 

TpPAMNotificationlnfoList 90 

PAM_CE_1DENT1TY_CREATED 90 

TpPAMlCEventData 90 

TpPAMlCNotificationData 90 

PAM_CE_1DENTITY_DELETED 90 

TpPAMlDEventData 90 

TpPAMlDNotificationData 91 

PAM_CE_GROUP_MEMBERSHIP_CHANGED 91 

TpPAMGMCEventData 91 

TpPAMGMCNotificationData 91 

PAM_CE_AGENT_CREATED 91 

TpPAMACEventData 91 

TpPAMACNotificationData 92 

PAM CE AGENT DELETED 92 



£75/ 





1.2 




2 




2.1 




2.2 




2.3 




2.4 




3 




3.1 




3.2 




3.3 




3.4 




4 




4.1 




5 




5.1 




5.2 




5.3 




6 




6.1 




6.2 




6.3 




6.4 




6.5 




7 




7.1 




8 




8.1 




8.2 




8.3 




8.4 




8.5 




8.6 




9 




9.1 




10 




11 




11.1 




11.2 




11.3 




12 




12.1 




12.2 




12.3 




12.4 




12.5 




12.6 




12.7 




12.8 




12.9 




12.10 




12.10.1 




12.10.2 




12.11 




12.11.1 




12.11.2 




12.12 




12.12.1 




12.12.2 




12.13 




12.13.1 




12.13.2 




12.14 



3GPP TS 29.198-14 version 6.3.1 Release 6 7 ETSI TS 129 198-14 V6.3.1 (2006-07) 

11.12.14.1 TpPAMADEventData 92 

11.12.14.2 TpPAMADNotificationData 92 

11.12.15 PAM_CE_AGENT_ASSIGNED 92 

11.12.15.1 TpPAMAAEventData 93 

11.12.15.2 TpPAMAANotificationData 93 

11.12.16 PAM_CE_AGENT_UNASSIGNED 93 

11.12.16.1 TpPAMAUEventData 93 

11.12.16.2 TpPAMAUNotificationData 94 

11.12.17 PAM_CE_CAPABILITY_CHANGED 94 

11.12.17.1 TpPAMCCEventData 94 

11.12.17.2 TpPAMCCNotificationData 94 

11.12.18 PAM_CE_AGENT_CAPABILITY_PRESENCE_SET 94 

11.12.18.1 TpPAMACPSEventData 95 

11.12.18.2 TpPAMACPSNotificationData 95 

11.12.19 PAM_CE_AGENT_PRESENCE_SET 95 

11.12.19.1 TpPAMAPSEventData 95 

11.12.19.2 TpPAMAPSNotificationData 96 

11.12.20 PAM_CE_IDENTITY_PRESENCE_SET 96 

11.12.20.1 TpPAMIPSEventData 96 

11.12.20.2 TpPAMIPSNotificationData 96 

11.12.21 PAM_CE_AVAILABILITY_CHANGED 96 

11.12.21.1 TpPAMAVCEventData 97 

11.12.21.2 TpPAMAVCNotificationData 97 

11.12.22 PAM_CE_WATCHERS_CHANGED 97 

11.12.22.1 TpPAMWCEventData 97 

11.12.22.2 TpPAMWCNotificationData 98 

11.12.22.3 TpPAMwatcherChangeType 98 

11.13 Error Types 98 

11.13.1 TpPAMErrorCause 98 

11.13.2 TpPAMErrorlnfb 98 

12 Presence and Availability Management Exception Classes 99 

Annex A (normative): OMG IDL Description of Presence and Availability Management 

SCF 100 

Annex B (informative): W3C WSDL Description of the Presence and Availability 

Management SCFs 101 

Annex C (informative): Java^^ API Description of the Presence and Availability 

Management SCFs 102 

Annex D (informative): Description of Presence and Availability Management for 3GPP2 

cdma2000 networks 103 

D.l General Exceptions 103 

D.2 Specific Exceptions 103 

D.2.1 Clause 1: Scope 103 

D.2.2 Clause 2: References 103 

D.2. 3 Clause 3: Definitions and abbreviations 103 

D.2.4 Clause 4: Presence and Availability Management SCF 103 

D.2. 5 Clause 5: Sequence Diagrams 103 

D.2. 6 Clause 6 Class Diagrams 104 

D.2. 7 Clause 7: The Service Interface Specifications 104 

D.2. 8 Clause 8: Presence and Availability Management Interface Classes 104 

D.2. 9 Clause 9: State Transition Diagrams 104 

D.2.10 Clause 10: PAM Service Properties 104 

D.2.1 1 Clause 1 1 : PAM Data Definitions 104 

D.2. 12 Clause 12: Presence and Availability Management Exception Classes 104 

D.2. 13 Annex A (normative): OMG IDL Description of Presence and Availability Management SCF 104 

D.2. 14 Annex C (informative): Java^"^ API Description of Presence and Availability Management SCF 104 



£75/ 



3GPP TS 29.198-14 version 6.3.1 Release 6 8 ETSI TS 129 198-14 V6.3.1 (2006-07) 

Annex D (informative): Change history 105 

History 106 



£75/ 



3GPP TS 29.198-14 version 6.3.1 Release 6 



ETSI TS 129 198-14 V6.3.1 (2006-07) 



Foreword 



This Technical Specification has been produced by the 3' Generation Partnership Project (3GPP). 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 
where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



The present document is part 14 of a multi-part TS covering the 3' Generation Partnership Project: Technical 
Specification Group Core Network and Terminals; Open Service Access (OSA); Application Programming Interface 
(API), as identified below. The API specification (3GPP TS 29.198) is structured in the following Parts: 



Parti 
Part 2 
Part 3 
Part 4 



Parts 
Part 6 
Part? 
Parts 
Part 9 
Part 10 
Part 11 
Part 12 
Part 13 
Part 14 
Part 15: 



"Overview"; 

"Common Data Definitions"; 

"Framework"; 

"Call Control"; 

Sub-part 1: "Call Control Common Definitions"; 

Sub-part 2: "Generic Call Control SCF"; 

Sub-part 3: "Multi-Party Call Control SCF"; 

Sub-part 4: "Multi-Media Call Control SCF"; 

Sub-part 5: "Conference Call Control SCF"; 

"User Interaction SCF"; 

"Mobility SCF"; 

"Terminal Capabihties SCF"; 

"Data Session Control SCF"; 

"Generic Messaging SCF"; 

"Connectivity Manager SCF"; 

"Account Management SCF"; 

"Charging SCF". 

"Policy Management SCF"; 

"Presence and Availability Management SCF"; 

"Multi Media Messaging SCF"; 



(not part of 3GPP Release 6) 



(not part of 3GPP Release 6) 
(not part of 3GPP Release 6) 



(new in Release 6) 



The Mapping specification of the OSA APIs and network protocols (3GPP TR 29.998) is also structured as above. 
A mapping to network protocols is however not applicable for all Parts, but the numbering of Parts is kept. 
Also in case a Part is not supported in a Release, the numbering of the parts is maintained. 
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OSA API specifications 29.198-family 


OSA API Mapping - 29.998-family 


29.198-01 


Overview 


29.998-01 


Overview 


29.198-02 


Common Data Definitions 


29.998-02 


Not Applicable 


29.198-03 


Framework 


29.998-03 


Not Applicable 


Call 
Control 
(CC) 
SCF 


29.198- 
04-1 

Common 
CC data 
definitions 


29.198- 
04-2 
Generic 
CCSCF 


29.198- 
04-3 
Multi- 
Party CC 
SCF 


29.198- 
04-4 
Multi- 
media CC 
SCF 


29.998-04-1 


Generic Call Control - CAP mapping 


29.998-04-2 


Generic Call Control - INAP mapping 


29.998-04-3 


Generic Call Control — Megaco mapping 


29.998-04-4 


Multiparty Call Control -ISC mapping 


29.198-05 


User Interaction SCF 


29.998-05-1 


User Interaction - CAP mapping 


29.998-05-2 


User Interaction - INAP mapping 


29.998-05-3 


User Interaction - Megaco mapping 


29.998-05-4 


User Interaction - SMS mapping 


29.198-06 


Mobility SCF 


29.998-06 


User Status and User Location - MAP mapping 


29.198-07 


Terminal Capabilities SCF 


29.998-07 


Not Applicable 


29.198-08 


Data Session Control SCF 


29.998-08 


Data Session Control - CAP mapping 


29.198-09 


Generic Messaging SCF 


29.998-09 


Not Applicable 


29.198-10 


Connectivity Manager SCF 


29.998-10 


Not Applicable 


29.198-11 


Account Management SCF 


29.998-11 


Not Applicable 


29.198-12 


Charging SCF 


29.998-12 


Not Applicable 


29.198-13 


Policy Management SCF 


29.998-13 


Not Applicable 


29.198-14 


Presence & Availability Management SCF 


29.998-14 


Not Applicable 


29.198-15 


Multi-media Messaging SCF 


29.998-15 


Not Applicable 
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Scope 



The present document is part 14 of the Stage 3 specification for an Apphcation Programming Interface (API) for Open 
Service Access (OS A). 

The OSA specifications define an architecture that enables application developers to make use of network functionality 
through an open standardised interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA 
are contained in 3GPP TS 23.198 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Presence and Availability Management Service Capability Feature (SCF) aspects of 
the interface. All aspects of the Presence and Availability Management SCF are defined here, these being: 

• Sequence Diagrams 

• Class Diagrams 

• Interface specification plus detailed method descriptions 

• State Transition diagrams 

• Data Definitions 

• IDL Description of the interfaces 

The process by which this task is accomplished is through the use of object modelling techniques described by the 
Unified Modelhng Language (UML). 

This specification has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and the Parlay Group, in co- 
operation with a number of JAIN^"^ Community member companies. 



References 



The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 



• 



• 



References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

For a specific reference, subsequent revisions do not apply. 

For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TS 29.198-1: "Open Service Access; Application Programming Interface; Part 1: 

Overview" . 

[2] 3GPP TS 22. 127: "Service Requirement for the Open Service Access (OSA); Stage 1 ". 

[3] 3GPP TS 23.198: "Open Service Access (OSA); Stage 2". 



3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the terms and definitions given in TS 29.198-1 [1] apply. 
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3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in TS 29.198-1 [1] apply. 

4 Presence and Availability Management SCF 

4.1 Introduction 

The goal of these interfaces is to establish a standard for maintaining, retrieving and publishing information about 

• Presence and Availability of entities for various forms of communication and the contexts in which they are 
available. 

4.2 Motivation 

Consider the following simple but desirable scenario for a communication service: An end-user wishes to receive 
instant messages from her management at any time on her mobile phone, from co-workers only on her desktop 
computer, and in certain cases for the messages to be forwarded to e-mail or even a fax machine/printer. The senders 
may know her availability for various forms of communication in the way she chooses to reveal it or alternatively the 
senders may never know how she will be receiving their messages. This scenario spans over multiple services and 
protocols and can only be solved currently by a proprietary solution that maintains the required information in an ad- 
hoc fashion within the application. 

PAM is not a replacement for the protocols being standardized for various communication and network services. PAM 
attempts to standardize the management and sharing of presence and availability information across multiple services 
and networks. 

The PAM specification is motivated by the observations that 

• The notions of Identity, Presence and Availability are common to but independent of the various communication 
technologies, protocols and applications that provide services using these technologies. 

• Presence does not necessarily imply availability. End-users or organizations require greater control over making 
themselves available through various communication devices. 



• 



Presence based services need to address privacy concerns on who can access presence information and under 
what conditions. 



Management of availability will span over multiple communication services and service providers. 

4.3 Goals 

The purpose of this document is to adopt the first release of a Presence and Availability Management interface 
specification created by an industry consortium, PAM forum, established for this purpose harmonized with the IETF 
model for presence (RFC 2778). This specification is also consistent with the ongoing work in 3GPP for defining the 
requirements and architecture for a standard presence service in the network. 

With a desired goal of rapid acceptance and usage, the specification has been deliberately designed to be as simple as 
possible with an attempt to include a minimal set of functionality that is sufficient for use in non-trivial applications. 
Often, this has been at the cost of some useful features, which would have made the specification baroque and 
cumbersome if not controversial. 



4.4 Concepts 



This chapter briefly describes the various concepts involved in this specification to serve as the context for the rest of 
the document. 
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4.4.1 Identity 



Identity, for purposes of the PAM specification, is a limited electronic representation of an entity (i.e., an individual or 
an organization) that participates in PAM-enabled applications and services. This concept corresponds to the concept of 
Presentity as described in the IETF Common Presence and Instant Messaging Model (RFC 2778). 

The main characteristic of an entity that is central to PAM specifications is the name (or handle) by which entities are 
identified by applications and services. Entities may have multiple names, login ids, account names, etc., by which they 
are identified. As PAM attempts to abstract over multiple networks and services, it does not assume that a single name 
will necessarily identify entities across all application domains. 

The generalized structure available in 3GPP for user names that may contain various formats for addressing has been 
adopted for these specifications. 

To enable entities to be identified by any of the names associated with them, PAM identities can be assigned aliases. A 
name and a namespace pair can be defined as an alias of another name and namespace pair. It is important to note that 
aliases are just synonyms and hence have limited semantics. In particular, they are not powerful enough to model 
personas each with their own capabilities and privacy requirements. 

An identity can represent a single entity or a group of identities. Group identities have similar semantics to non-group 
identities but, in addition, maintain a list of identities that constitute the group. As an example, a sales department may 
be modelled as a group identity with the identities of the members of the department being member identities of the 
group. Group identities and their member identities do not inherit anything from each other. 

No other relationships between identities are within the scope of the PAM specifications. 

For flexibility and extensibility, attribute lists are used to associate additional data with identities. Identities are typed to 
provide a way to manage such attribute lists. An identity type may be associated with a specific set of attributes and all 
identities of that type inherit instances of such attributes. 

For consistency with IETF (RFC 2778) defined presence data models, PAM pre-defines an identity type Presentity with 
a list of presence attributes as defined in TS 22.141 based on the definitions in RFC 2778. 

PAM implementations may map certain existing directory and database data to one or more types to allow access via 
PAM interfaces. PAM specifications do not specify how the data within the profiles are to be stored. They may be 
stored within the PAM implementation or mapped to data stored on external directories and databases. 

4.4.2 Presence 

The concept of presence has been used in several application areas, being most explicit in Instant Messaging. Starting 
from a simple notion of online/offline status, it has expanded to include other context information around the status such 
as disposition (out to lunch, away from the computer, etc.) and activity status (on the phone, idle, etc.). Location 
information, on the other hand, has largely been kept separate from what has been traditionally considered presence 
information. PAM specifications broaden the concepts of presence recognizing that all such information, including 
location, describes different contexts of an entity's existence. The unifying property is that the presence information is 
continually changing and that there is value in knowing the current information at different points in time for services 
and applications. 

For the purposes of PAM specifications, presence is an extensible set of characteristics that captures the dynamic 
context in which an identity or an agent exists at any point in time. In contrast to the relatively static information about 
identities or agents (e.g., names, addresses, capabilities), presence refers to dynamic information such as location, 
status, disposition, etc. Registrations of presence and location information in existing applications are covered by this 
definition. 

Presence information is differentiated from the more static information associated with identities and agents that are 
stored in attributes. The rationalization for this design is that the presence information is dynamic and has implications 
on the implementation. Some of the presence information is too dynamic to be maintained in static data stores such as 
directories and without this hint about the data characteristics, PAM implementers may make sub-optimal decisions on 
the way the data is stored. Second, presence information typically has expiration data that needs to be understood by the 
implementation. 

The PAM specification recognizes that devices that provide presence information are not necessarily devices that 
communicate. 
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The PAM specification does not specify the methods by which the presence information is derived. For example, an 
instant messaging cHent on a desktop computer can register its status based on when a user is logged in. A mobile 
phone may do an explicit registration on a WAP server for instant messaging. The phone's presence for voice calls, on 
the other hand, may be inferred implicitly by querying the cellular network for the device being on when requested. The 
presence of an identity, on the other hand, may be computed using presence information from one or more devices 
owned by the identity. 

Finally, the PAM specification does not require that the presence information be stored explicitly (i.e., in a materialized 
fashion) in a PAM implementation. An implementation may infer the presence information on demand from the 
underlying services or networks. 

For compatibility with the presence model from IETF (RFC 2778), a type called Presentity is pre-defined with the 
attributes consistent with the IETF Presence model. 



4.4.3 Availability 



Availability is a property of an identity denoting its ability and willingness to share information about itself or to 
communicate with another identity based on factors such as the type of communication requested, the identity of the 
calling entity and the preferences and policies that are associated with the recipient. This is the primary means by which 
the current PAM specification enables controls for privacy. While presence is, in most applications, a necessity for 
availability, presence does not necessarily imply availability to all. 

Availability is always with respect to a context. A context in PAM specifications is a set of attributes defining the state 
in which the availability is requested. For example, the query "Is Jane available for IM for Rob?" identifies the type of 
communication and the identity of the asker as the context. PAM allows for availability to be differentiated based on 
any attribute of a context. A context, "Communication" is pre-defined in PAM. 

Most queries for presence in existing applications can be mapped into PAM availability queries to control the 
information being given out. Alternatively, queries can be mapped directly into PAM presence queries in situations 
where privacy controls and policies are not required or all presence data is open to the entity querying. This allows 
PAM specifications to be consistent with existing presence servers and to serve as the basis for presence services across 
multiple protocols while providing uniform and flexible privacy controls. 

PAM specification does not specify whether the availability is computed on demand or stored explicitly. In some 
applications, the availability may be pre-computed and stored explicitly while in some, it may be computed at each 
request for availability. 

While the PAM specification provides a mechanism to associate preferences with an Identity to control availability, it 
neither specifies the syntax and semantics of the preferences nor the process by which the availability is computed. 
These aspects are left to the implementation. 

For example, a particular implementation may provide the facility to store preferences as rules such as "I prefer to 
receive my instant messages on my computer rather than my cell phone unless the message is from my boss or the 
computer is off, etc.". 

As an example, a computation of availability for communication may consist of the following algorithm: 

1) Find all devices of the identity being called that are capable of the specified form of communication AND have 
registered their presence status as available. 

2) Evaluate the rules associated with the identity being called to select the preferred device(s) from the set of 
present devices determined in Step 1 . 

3) If there are any devices available satisfying Step 2, indicate the availability of the identity being called via the 
available devices. 

An implementation can chose to provide one or more means to specify preferences. It is expected that if there is 
industry standardization on the specification of preferences, the implementations will support such a standard. This is 
currently outside the scope of PAM. 
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4.4.4 Events 

Events are representations of certain identified occurrences related to the concepts described above. The PAM 
specification provides for registering interest (i.e., callbacks) in being notified of such occurrences. Any entity that 
subscribes to the Event is a "watcher" in the IETF terminology (RFC 2778). An implementation is expected to provide 
such notifications. 

Examples of events include, 

• Creation/deletion of an identity. 

• Change in the presence information of an identity 

• Change in availability of an identity for a particular form of communication 

PAM specifications contain a set of pre-defined events. Each event is defined by a name of the event, a set of input 
attribute value pairs that must be provided when an event is registered for and a set of attribute value pairs that are 
included in the notifications sent out when the event of interest occurs. 

4.5 Scope of PAM information 

Presence and Availability Management has the following types of information in its scope: 

• Identities, which consist of names and aliases of entities participating in communications. 

• Presence information, which consists of an identity's dynamic characteristics such as status and geographical 
location. 

• Availability information, which consists of preferences associated with identities and computation of 
availability, based on the devices present and the current preferences. 

• Notification of changes to the above pieces of information. 

• Security issues for access to this information. 

The PAM specification consists of interfaces to manage or access the above information. 
The specification purposefully does not include 

• Storage design or storage requirements for any of the presence and availability information. 
These are to be decided by specific implementations of the PAM specification. 



4.6 Security and privacy 



As the Presence and Availability Management interface is designed to share information across administrative domains 
and to facilitate availability computation based on the identity of the entity desiring communication, security and 
privacy issues are addressed in the design. Two of the issues considered to be within the scope of PAM are: 

• Access control to an implementation of the PAM specification. 

• Use of an authenticated entity' s credentials by methods in the specification. 

To understand the distinction between the first two issues, consider, for example, an end-user that logs on to an Instant 
Messaging client and wishes to send a message. The client (or a gateway to which the client talks to) may access a PAM 
implementation to determine the availability of the destination for the message. The client (or the gateway) will need to 
be authorized for access to the PAM implementation independent of the user that logs in. A gateway may, in fact, do 
this access on behalf of a number of clients and, for performance reasons, wish to authenticate itself just once on start 
up rather than at each invocation. This authentication is handled by the authentication mechanisms in the OSA 
Framework common to all services within OSA. 

Second, each invocation of a particular method will need to contain the credentials of the end-user that logged into the 
client so that the computation of the availability can take that into account when necessary for privacy issues. 
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It should be noted that the PAM specification allows for the possibility that the authentication of the end-users is not 
necessarily done within the PAM implementation itself. As long as the authenticated credentials supplied by the client 
(or gateway) are acceptable for validation and the client (or the gateway) itself is authenticated by the implementation, 
the authentication of end-users can occur anywhere outside the PAM implementation. A deployment scenario for a 
particular application is that one or more authentication services are provided as external services over PAM 
implementations. 

This design does not preclude the possibility that the client (or the gateway) cannot be authenticated. Therefore, the 
credentials supplied by the client (or the gateway) may be held to stronger authentication criterion than credentials 
supplied by a trusted client (or gateway). 

Finally, the PAM specification does not mandate the use of authentication within an implementation if the environment 
in which it is used does not require it. 

Clause 5.1 explains the mechanism for providing data about the asker to each of the methods with a sequence diagram. 

Privacy issues are addressed primarily by providing a mechanism to control the information flowing out of a PAM 
implementation based on whatever criterion the end user may choose to specify in the availability preferences and 
independent of any particular application. 

The following security issues were considered to be outside the scope of PAM: 

• Authentication of the identity of the end-users or entities. As explained above, this authentication may be 
provided by a third-party authentication service or it may occur through an authentication service written over 
the PAM platform. The only requirement is that the type of credentials supplied by the authentication service be 
acceptable to the PAM platform implementation being accessed. 

• Encryption of the flow of information between a PAM platform implementation and clients of this 
implementation. This is dependent on the method of access to the interface which is outside the scope of the 
PAM specification and hence to be determined by the implementation. 



Sequence Diagrams 



Most of the methods in the PAM interfaces are independently used to query or update presence and availability related 
information with no transactions or state transitions involved. There are two use cases for which sequence diagrams are 
useful 

• Acquiring and using authentication tokens 

• Registering for PAM events and getting notifications on the occurrence of the event. 

The sequence diagrams for these two cases are provided below. It is assumed that the authentication with the OSA 
framework has already occurred and the application has access to the PAM interfaces. 

5.1 Use of authentication tokens 

As an OSA Service, PAM uses the authentication features of the OSA Framework to provide access control to the PAM 
interfaces. In addition, PAM provides an optional mechanism for service/application level identification and 
authentication of the entity requesting the operation or alternatively on whose behalf the operation is being requested. 
To handle privacy requirements, the results of presence and availability data updates or queries are dependent on the 
entity requesting the operations. 

In the simplest case, the entity authenticating to the OSA Framework to get access to the service interface is the entity 
requesting the operation. In general, however, a proxy or an application (such as a messaging server or a conferencing 
server) may authenticate with the OSA Framework once and then check for presence and availability on behalf of 
multiple client applications (such as instant messaging clients). The credential of these client applications if and when 
needed by the PAM service can then be provided via the credential parameter in each of the interface methods. 
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The mechanism to provide the asker data is via the optional parameter of type TpPAMCredential in each of the 
methods. Supplying the entire asker data in each of the methods is expensive for an implementation since it will need to 
parse and validate the data supplied in the asker data structure each time. An application may be accessing multiple 
methods for itself or for the benefit of end user(s) and will need to supply the relevant asker data in each case. To make 
the consideration of asker data more efficient, the application uses the getAuthToken() method in each of the managers 
in the SCFs once for each session per asker and gets a credential that can be reused as many times as necessary in the 
same session to represent the same asker. 

The sequence diagram for an example usage is given below. 



Client 



IpPAMPresenceAvailabilitvManaqer 

I 

1: getAuthToken( ) 



IpPAMIdentityPresence IpPAMAvailabilitv 



2: getlclentityPi*esence{ 



-»r 



3: getAvailability( ) 



^ 



1: For any unique entity requesting the operation, the authenticated client of the OS A PAM service, requests for an 
authentication token using the getAuthToken() method in the PresenceAvailability Manager interface. 

2: The token returned by the getAuthToken() method is used as the credential parameter of the getIdentityPresence() 
request. 

3: The same token is used as the credential parameter of the getAvailabilityO request(). An authorization token can be 
used multiple times within the same session established with OSA framework. 



5.2 Event registration and notification 

An OSA client can register for certain events in the PAM service either for itself or on behalf of its own clients. The 
client will register one or more application interfaces with the event management service and then activate one or more 
events for each such registered interface. 

The sequence diagram for an example is given below. 
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: IpAppPAMEventHandler 



Client 1 : IpPAMEvenlHandler 

\ \ 

1 : regis terApplnterface( ) 



^ 



2: getAuthToken{ ) 



3: registerForE\ent( ) 



-^ 



5: evet]itNotify( ) 



IpPAMEventManager Ip PA M Identi ty Presence 



-^ 



; setldentityPresence( ) 



1 : The client uses the registerAppInterface() method to register its notification interface. The getAuthToken() can be 
null since the client is doing this registration on its own behalf. The client gets a unique client ID back. 

2: The client uses the getAuthToken() to get authentication credentials for its own appUcation cUent on behalf of whom 
an event registration is required. 

3: The client uses the registerForEvent() method to register for a change in availability event on behalf of its own 
client. The client gets a unique event ID back. 

4: The presence information for an identity of interest in 3 above is changed by another client application acting on its 
behalf using the setIdentityPresence() method. 

5: When the change in presence results in a change in the availability of the identity for the client that has registered 
for the availability change, a notification is sent out using the previously registered application interface. 



Class Diagrams 



PAM consists of the following SCFs: 

• PAM Provisioning Service consisting of Interfaces to provision identities, agents and relationships between them 

• PAM Access Service consisting of interfaces to view and update presence and availability information and 

• PAM EventManagement Service consisting of interfaces to subscribe to events in PAM and be notified of such 
events. 

6.1 PAM Provisioning SCF Class Diagrams 

PAM Provisioning Service contains the following service interfaces. It contains no application interfaces. 

IpPAMIdentityManagement 

- The purpose of this interface is to manage subscriber names, aliases, groups and sets of attributes called Profiles 
associated with subscribers. 

IpPAMAgentManagement 
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- The purpose of this interface is to manage agent (that models a hardware or software device) names, communication 
capabihties and sets of attributes called Profiles associated with agents. 

IpPAMAgentAssignment 

- The purpose of this interface is to manage the relationship between identities and the agents assigned to them. 
IpPAMIdentityTypeManagement 

IpPAMAgentTypeManagement 
IpPAMCapabilityManagement 

- These three interfaces allow for definitions of identity types, agent types and agent capabihties used for presence and 
availability management. 

The interfaces and the relationships between them are shown in the figure below. 



<<lnterface» 
IpPAM IdentityM anag ement 

(from provisioning) 

''icreateJctenliVO 

%leletelcten1ti<) 

^sldentiVO 

*createGroLplcfen1iti< ) 

%le leteG r oiplde ntit i< ) 

•*BddTcGroLp() 

■*remo\eFromGroLp() 

%is1Vlembers( ) 

^sGroupldentiVO 

"•l is IGr oipM embe rsh ip() 

%ddAlias() 

■•remo\eAliases() 

■**is1Aliases() 

■^ockupByAliasQ 

■%sscci£teTypes{) 

%li sas scciateTypes 

■*lisfrypesOtldentiV() 

%iasTipe() 

■^etldentit/AttrbutesO 

%e1lcfentJVAtlrbutes() 




<<lnterface>> 
IpPAM Ag entTypeM anag ement 

itrom provisionlngi 

''Kt eS e/ig e ntA It ri tut e( ) 
"Irte let e'\g e ntAtt ri fcu te ( ) 
'%getAgentAttribiieDefinition() 
■*J!stAIIAgertAtlributes() 
■^T eS eAg e nfT ype () 
'%:telete'\gentTipe() 
''MistAgenfrypesO 
''teddAgentTypo^ttribUesO 
*re mo\fi Ag ert Tjp eAtIr lb utes ( ) 
pi( is lAg e nfT ype Att ri fcu tes ( ) 



<<lnterface» 
IpPAM Ag entM anag ement 

(from provisioninol 



■*breateAgert() 
■*de leteAg ent () 
^sAgent;) 
^^n^l eCapab lilies 
BbisableCapabilitiesf ^ 
^ is lEn Ebl edC ap sbi I i t ie s{) 
■*)istAIICapabilities() 
^sCapabeOf() 
issociateTypesO 
sassociateTypesO 
isfTypesOfAgentO 
iasType() 

etAgen1Attributes() 
etAgertA tributes 




«lnterface>> 
IpPAM Provisioning Manager 

(from provisioning) 

■*getAuthToten() 

%)btainlnterface() 
^;<new» getAccessControlO 
^;<new» setAccessControlO 



«uses» 



V 

«lnterface>> 
IpPAM CapabilityM anag ement 

(from provisioning) 



■*fcreateCapabilityAttribute() 
*deleteCapabilityAttribute() 
■*getCapabilityAttributeDefinition() 
■*iistAIICapabilityAttributes() 
■*treateCapability() 
■*deleteCapability() 
■*1istCapabilities() 
■*addCapabilityAttributes() 
■%emoveCapabilityAttributes() 
■*<istCapabilityAttributes() 
^l«ssignCapabilitiesToType() 
'%unassignCapabilitiesFromType() 
^istCapabilitiesOfType{) 



<<lnterface>> 
IpPAM Ag entAssig nment 

(from provisioning) 



BssignAgentO 

LnassignAgentO 

listAssignedAgentsO 

listAssociatedldentitiesOfAgentO 

(istAssignedAgentsByCapabilityO 

^istCapabilitiesOfldentityO 

|sldentityCapableOf{) 

A 



«lnterface>> 
IpPAM Identity! ypeM anag ement 

(from provisioning) 

:reateldentityAttribute() 
heleteldentityAtlributeO 
petldentityAttributeDe1inition() 
[istAllldentityAttributesO 

;reateldentityType() 
heleteldentityTypeO 
listldentityTypesO 
liddldentityTypeAttributesO 
femoveldentityTypeAttributesO 
jistldentityTypeAttributesO 



Figure: RAM Provisioning Service 



6.2 RAM Access SCF Class Diagrams 

The PAM Access service consists of two packages, one for the apphcation interfaces and one for the service interfaces. 
The apphcation PAM Access package consists of or more instances of the IpAppPAMPreferenceCheck interface and 



ETSI 



3GPP TS 29.198-14 version 6.3.1 Release 6 



20 



ETSI TS 129 198-14 V6.3.1 (2006-07) 



the PAM event management service package consists of a single instance of the following interfaces obtainable by 
applications using the service interface IpPAMPresenceAvailabilityManager. 

IpPAMIdentityPresence 

- The purpose of this interface is to maintain the dynamic presence information of identities. 
IpPAMAvailabilityManagement 

- The purpose of this interface is to (i) Manage the preferences specified for the availability of an identity (ii) Query for 
the availability of identities for specific capabilities. 

The interfaces and the relationships between them are shown in the figure below. 



-{> 



<<lnterface>> 
Iplnterface ^^i 

{from csapi) "^^ 



<<lnterface>> 
IpAppPAM PreferenceCheck 



(from access) 



computeAvailabilityO 



<<uses>> 



<<uses>> 



<<lnterface>> 
IpPAMAvailability 

(from access) 



getAvailabilityO 
getPreferenceO 
setPreferenceO 



<<uses>> 



<<lnterface>> 
IpPAMIdentityPresence 

(from access) 

setldentityPresenceO 

5etldentityPresenceExpiration() 

getldentityPresenceO 



<<lnterface>> 
IpService 

(from csapi) 



3etCallback() 
3etCallbackWithSessionlD() 



<<lnterface>> 
^DPAMPresenceAvailability Manager 

(from access) 



^getAuthTokenO 
^obtainlnterfeceO 
^<<new>> getAccessControlO 
|P<<new>> setAccessControlO 
^<<new>> activateServiceO 
P<<new>> deactivateServiceO 
B<<new>> isActiveldentityO 



Figure: PAM Access Service 



6.3 PAM Event SCF Class Diagrams 

The PAM Event Management service consists of two packages, one for the application interfaces and one for the 
service interfaces. The application PAM event management package consists of or more instances of the 
IpAppPAMEventHandler interface and the PAM event management service package consists of a single instance of the 
IpPAMEventHandler interface. This interface can be obtained by application using the service interface 
IpPAMEventManager. 

The figure below shows the interfaces of PAM Event Management and the relationships between them. 
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«lnterfac... 
Iplnterface 

(from csapi) 



TV 



«lnterface» 
IpAppPAMEventHandler 

(from event) 



^eventNotifyO 
[ *eventNotifyErr() 



«uses» 



«lnterface» 
IpPAMEventHandler 

(from event) 



[sRegisteredO 
J-egisterApplnterfaceO 
J-egisterForEventO 
|deregisterApplnterface() 
IderegisterFrom Event{) 



<<lnterface» 
IpService 

(from csapi) 



P^setCailbackO 
fc^setCallbackWithSessionlDO 



TV 



<<lnterface» 
IpPAMEventManager 

(from event) 

HgetAuthTokenO 
HobtainlnterfaceO 
B«new>> getAccessControlO 
Pi'«new>> setAccessControlO 
|*«new>> activateServiceO 
r*«new>> deactivateServiceO 
*«new>> isActiveldentityO 



«uses>> 



Figure: PAM Event Management Service 



7 The Service Interface Specifications 

7.1 Interface Specification Format 

This clause deiines the interfaces, methods and parameters that form a part of the API specification. The Unified 
ModelHng Language (UML) is used to specify the interface classes. The general format of an interface specification is 
described below. 



7.1.1 



Interface Class 



This shows a UML interface class description of the methods supported by that interface, and the relevant parameters 
and types. The Service and Framework interfaces for enterprise-based client applications are denoted by classes with 
name Ip<name>. The callback interfaces to the applications are denoted by classes with name IpApp<name>. For 
the interfaces between a Service and the Framework, the Service interfaces are typically denoted by classes with name 
IpSvc<name>, while the Framework interfaces are denoted by classes with name IpFw<name>. 



7.1.2 



Method descriptions 



Each method (API method "call") is described. Both synchronous and asynchronous methods are used in the API. 
Asynchronous methods are identified by a 'Req' suffix for a method request, and, if applicable, are served by 
asynchronous methods identified by either a 'Res' or 'Err' suffix for method results and errors, respectively. To handle 
responses and reports, the application or service developer must implement the relevant IpApp<name> or 
IpSvc<name> interfaces to provide the callback mechanism. 
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7.1.3 Parameter descriptions 

Each method parameter and its possible values are described. Parameters described as 'in' represent those that must have 
a value when the method is called. Those described as 'out' are those that contain the return result of the method when 
the method returns. 

7.1.4 State Model 

If relevant, a state model is shown to illustrate the states of the objects that implement the described interface. 

7.2 Base Interface 

7.2.1 Interface Class Iplnterface 

All application, framework and service interfaces inherit from the following interface. This API Base Interface does not 
provide any additional methods. 



«lnterface» 
Iplnterface 



7.3 Service Interfaces 
7.3.1 Overview 

The Service Interfaces provide the interfaces into the capabilities of the underlying network - such as call control, user 
interaction, messaging, mobility and connectivity management. 

The interfaces that are implemented by the services are denoted as 'Service Interface'. The corresponding interfaces that 
must be implemented by the application (e.g. for API callbacks) are denoted as 'Application Interface'. 

7.4 Generic Service Interface 
7.4.1 Interface Class IpService 

Inherits from: Iplnterface 

All service interfaces inherit from the following interface. 



«lnterface» 
IpService 



setCallback (applnterface : in IplnterfaceRef) : void 

setCallbackWitlnSessionlD (applnterface : in IplnterfaceRef, sessionID : in TpSessionID) : void 
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7.4.1.1 Method setCallback() 

This method specifies the reference address of the callback interface that a service uses to invoke methods on the 
application. It is not allowed to invoke this method on an interface that uses SessionlDs. Multiple invocations of this 
method on an interface shall result in multiple callback references being specified. The SCS shall use the most recent 
callback interface provided by the application using this method. In the event that a callback reference fails or is no 
longer available, the next most recent callback reference available shall be used. 

Parameters 

applnterface : in IpInterfaceRef 

Specifies a reference to the application interface, which is used for callbacks. 

Raises 

TpCommonExceptions , P_INVALID_INTERFACE_TYPE 



7.4.1.2 Method setCallbackWithSessionlD() 

This method specifies the reference address of the application's callback interface that a service uses for interactions 
associated with a specific session ID: e.g. a specific call, or call leg. It is not allowed to invoke this method on an 
interface that does not use SessionlDs. Multiple invocations of this method on an interface shall result in multiple 
callback references being specified. The SCS shall use the most recent callback interface provided by the application 
using this method. In the event that a callback reference fails or is no longer available, the next most recent callback 
reference available shall be used. 

Parameters 

applnterface : in IpInterfaceRef 

Specifies a reference to the application interface, which is used for callbacks. 

sessionID : in TpSessionID 

Specifies the session for which the service can invoke the application's callback interface. 

Raises 

TpCommonExceptions, P_INVALID_SESSION_ID, P_INVALID_INTERFACE_TYPE 



8 Presence and Availability Management Interface 

Classes 

PAM consists of the following SCFs 

• PAM Provisioning Service 

• PAM Access Service 

• PAM Event Service 

The PAM Provisioning service consists of the Identity Management, Agent Management, Agent Assignment, Agent 
Type Management, Identity Type Management and Capability Management interfaces. 

The PAM Access service consists of the identity presence and availability interfaces. 
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The Event service consists of the Event Management interfaces. 

An implementation of this API which supports or implements a method described in the present document, shall 
support or implement the functionality described for that method, for at least one valid set of values for the parameters 
of that method. Where a method is not supported by an implementation of a Service interface, the exception 
P_METHOD_NOT_SUPPORTED shall be returned to any call of that method. 

8.1 PAM Provisioning SCF Interface Classes 

This service consists of interfaces to provision identities, agents and the relationships between them. 

8.1 .1 Interface Class IpPAMProvisioningManager 

Inherits from: IpService. 

The purpose of this interface is to supply the various interfaces available in this service to the application and to provide 
the authentication credentials. This interface is the only discoverable interface from the framework. 

All PAM methods use an authentication token as a parameter since the outcome of the operations may depend on 
the entity requesting the operation. To enable this, the getAuthToken() method is used to obtain an implementation 
dependent token. An application that has authenticated itself with the OSA framework, can get an authentication token 
for itself. Alternatively, if the application is requesting PAM operations on behalf of multiple entities, authentication 
tokens may be requested for each such entity after providing any available data about the asker. These tokens can then 
be used repeatedly for operations within a session without further need to identify the asker. 



«lnterface» 
IpPAMProvisioningManager 



getAutin Token (askerData : in TpAttributeList) : TpPAMCredential 

obtainlnterface (interfaceName : in TpPAMProvisioninglnterfaceName) : IplnterfaceRef 

«new» getAccessControl (identity : in TpPAMFQName, autiiToken : in TpPAMCredential) : 
TpPAMAccessControl Data 

«new» setAccessControl (identity : in TpPAMFQName, operation : in TpPAMPreferenceOp, 
newAccessControl : in TpPAMAccessControl Data, authToken : in TpPAMCredential) : void 



8.1 .1 .1 Method getAuthTokenQ 

Get an authentication token for access to the interface methods. 

Returns an implementation-dependent authentication credential that can be verified. 

Parameters 

askerData : in TpAttributeList 

Specifies information about the asker. Can be an empty array. The exact attributes in this list are dependent on the 
application. PAM reserves the attribute "name" with type TpPAMFQName to contain the identity of the asker if known. 
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Returns 
TpPAMCredential 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1 .1 .2 Method obtain lnterface() 

Obtain available interfaces from the service. The valid parameters for this method can be obtained from the service 
property P_OBTAINABLE_INTERFACES . 

Returns the requested interface. 

Parameters 

interfaceName : in TpPAMProvisioninglnterfaceName 

Specifies the name of the required interface. 

Returns 
IpInterfaceRef 

Raises 

TpCommonExceptions , P_PAM_UNAVAILABLE_INTERFACE 



8.1 .1 .3 Method «new» getAccessControl() 

Get the access control associated with the data belonging to an identity. The data associated with an identity includes 
the static and dynamic attributes of an identity as well as data about agents associated with an identity. 

This method should be used in conjunction with the setAccessControl method. 

Returns the access control if previously specified for the identity. Is null if there is no access control associated. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Returns 
TpPAMAccessControlData 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1 .1 .4 Method «new» setAccessControl() 

Set the access controls for the data associated with the specified identity. If the identity is Null, the access control is set 
for all identities (if authorized to do so). The data associated with an identity includes the static and dynamic attributes 
of an identity as well as data about agents associated with an identity. 

Any existing access control will be modified based on the operation. 

If the new access control is specified as Null for replace operation , an existing access control will be removed. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

operation : in TpPAMPreferenceOp 

Specifies the operation to be performed with the specified preference. 

newAccessControl : in TpPAMAccessControlData 

Specifies the access controls to add. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1 .2 Interface Class IpPAMIdentityManagement 

Inherits from: Iplnterface. 

The purpose of this interface is to manage end-user or entity names, aliases, groups and sets of attributes associated with 
identities. An implementation may map these methods to operations on existing directories or databases. Some 
implementations may choose to provide a read-only access to the identity information. 

The names of identities within a namespace must be unique. Each implementation exports an identifier as the default 
namespace that it serves. The identity name and the namespace may be used as an alias to another identity in a different 
namespace. 

Aliases are associated with a given identity or group identity. Aliases must be uniquely assigned. In other words, 
two identities may not share the same alias. 

This interface is meant for use by provisioning applications that establish and maintain identity names. 
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«lnterface» 
IpPAMIdentityManagement 



createldentity (identity : in TpPAMFQName, identityTypes : in TpStringList, autin Token : in 
TpPAMCredential) : void 

deleteldentity (identity : in TpPAMFQName, autin Token : in TpPAMCredential) : void 

isldentity (identity : in TpPAMFQName, autiiToken : in TpPAMCredential) : TpBoolean 

createGroupldentity (identity : in TpPAMFQName, identityTypes : in TpStringList, authToken : in 
TpPAMCredential) : void 

deleteGroupldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : void 

addToGroup (group : in TpPAMFQName, member : in TpPAMFQName, authToken : in TpPAMCredential) : 
void 

removeFromGroup (group : in TpPAMFQName, identity : in TpPAMFQName, authToken : in 
TpPAMCredential) : void 

listMembers (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQNameList 

isGroupldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpBoolean 

listGroupMembership (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQNameList 

addAlias (identity : in TpPAMFQName, alias : in TpPAMFQName, authToken : in TpPAMCredential) : void 

removeAliases (identity : in TpPAMFQName, alias : in TpPAMFQName, authToken : in TpPAMCredential) : 
void 

listAliases (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQNameList 

lookupByAlias (alias : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQName 

associateTypes (identity : in TpPAMFQName, identityTypes : in TpStringList, authToken : in 
TpPAMCredential) : void 

disassociateTypes (identity : in TpPAMFQName, identityTypes : in TpStringList, authToken : in 
TpPAMCredential) : void 

listTypesQfldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQNameList 

hasType (identity : in TpPAMFQName, typeName : in TpString, authToken : in TpPAMCredential) : 
TpBoolean 

getldentityAttributes (identity : in TpPAMFQName, IdentityType : in TpString, attributeNames : in 
TpStringList, authToken : in TpPAMCredential) : TpPAMAttributeList 

setldentityAttributes (identity : in TpPAMFQName, IdentityType : in TpString, attributes : in 
TpPAMAttributeList, authToken : in TpPAMCredential) : void 



8.1.2.1 Method createldentityO 

Create a new non-Group Identity with the specified name. Names must be unique across both group identities and non- 
group identities. Names must be unique across types within a namespace. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be created. 
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identityTypes : in TpStringList 

Specifies the identity's associated types. Can be an empty array. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_IDENTITY_EXISTS, P_PAM_UNKNOWN_TYPE , 
P PAM INVALID CREDENTIAL 



8.1 .2.2 Method deleteldentity() 

Delete the specified identity and all its related data. Upon successful completion, associated aliases and attribute 
instances are deleted from the system. The identity is also removed from all groups of which the identity is a member. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be deleted. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.2.3 Method isldentityO 

Check if the specified non-group Identity exists. The method returns false for group identities. 
Returns true if an identity with the specified name exists and false otherwise. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be checked. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 
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8.1.2.4 Method createGroupldentityQ 

Create a new Group Identity with the specified name. Name must be unique across both group identities and non-group 
identities. Names must be unique across the same types. 

Parameters 

identity : in TpPAMFQName 

Specifies the group Identity to be created. 

identityTypes : in TpStringList 

Specifies the group's associated types. Can be an empty array. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_IDENTITY_EXISTS, P_PAM_UNICNOWN_TYPE , 
P PAM INVALID CREDENTIAL 



8.1 .2.5 Method deleteGroupldentityQ 

Delete the specified group identity and all its related data. Upon successful completion, associated aliases and attribute 
instances are deleted from the system. The identity is also removed from all groups of which the identity is a member. 
The member identities of the group are not deleted. 

Parameters 

identity : in TpPAMFQName 

Specifies the group Identity to be deleted. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1 .2.6 Method addToGroupQ 

Add an existing identity to a group identity. Both the group identity and the member identity to be added must have 
been created before this operation can be invoked. A member identity can be a group identity. Implementation must not 
allow cycles in memberships. 

Parameters 

group : in TpPAMFQName 

Specifies the group Identity to which the member will be added. 
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member : in TpPAMFQName 

Specifies the identity to be added as a member of the group. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_MEMBER_EXISTS, P_PAM_UNICNOWN_GROUP , 
P_PAM_UNKNOWN_MEMBER, P_PAM_IS_CYCLIC, P_PAM_INVALID_CREDENTIAL 



8.1.2.7 Method removeFromGroupO 

Remove an existing identity from the membership of a group identity. 

Parameters 

group : in TpPAMFQName 

Specifies the Group Identity from which the member will be removed. 

identity : in TpPAMFQName 

Specifies the Identity to be removed as a member of the group. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_NOT_MEMBER, P_PAM_UNKNOWN_GROUP , 
P_P AM_UNKNOWN_MEMBER , P_P AM_INVAL ID_CREDENT lAL 



8.1.2.8 Method listMembersO 

List the members of the specified group Identity. 

Returns a list of members of the specified group Identity. An empty list is returned if the identity has no members. 

Parameters 

identity : in TpPAMFQName 

Specifies the group Identity whose members are required. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Returns 

TpP AMFQNameLi s t 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_GROUP , P_PAM_INVALID_CREDENTIAL 



8.1.2.9 Method isGroupldentityO 

Check if the specified group identity exists. The method returns false for non-group identities. 
Returns true if a group identity with the specified name exists, false otherwise. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be checked. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1.2.10 Method listGroupMembership() 

List the Group Identities the specified Identity is a member of. 

Returns a list of all groups the specified Identity is member of. An empty list is returned if the identity is not member of 
any group. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be looked up. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Returns 

TpP AMFQNameLi s t 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.2.11 Method addAliasQ 

Add an alias in the specified namespace to an existing Identity. The alias domain name must be specified in Alias 
parameter. The identity can be a group identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to which the alias will be added. 

alias : in TpPAMFQName 

Specifies the alias to be added. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_ALIAS_EXISTS, P_PAM_ALIAS_NOT_UNIQUE, 
P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.2.12 Method removeAliases() 

Remove the specified alias from an existing identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity from which the alias will be deleted. 

alias : in TpPAMFQName 

Specifies the alias to be deleted. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_UNASSIGNED_ALIAS, 
P PAM INVALID CREDENTIAL 
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8.1.2.13 Method listAliasesQ 

List the aliases of the specified Identity. 

Returns a list containing all aliases to the specified Identity. A list with zero elements is returned if there are no aliases 
associated with the identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be looked up. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 

TpP AMFQNameLi s t 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.2.14 Method lookupByAliasQ 

Find the identity with the specified alias in the specified alias domain. 

Returns the identity that has the specified alias. Returns null if the alias is not assigned to any identity. 

Parameters 

alias : in TpPAMFQName 

Specifies the alias to be looked up. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMFQName 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_ALIAS , P_PAM_INVALID_CREDENTIAL 



8.1 .2.15 Method associateTypesQ 

Associate an identity instance with the specified types. The identity will be associated with instances of any attributes 
defined with each type. The initial values of the attributes will be as specified in the definition of the type attributes. 
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Parameters 

identity : in TpPAMFQName 

Specifies the name of the identity. 

identityTypes : in TpStringList 

Specifies the names of the type to be associated. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_UNKNOWN_TYPE, 
P_PAM_TYPE_ASSOCIATED , P_PAM_INVALID_CREDENTIAL 



8.1 .2.1 6 Method disassociateTypesQ 

Remove the association of a type with an identity instance. The definition of the type itself remains unaffected and the 
types may continue to be associated with other identities. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity. 

identityTypes : in TpStringList 

Specifies the names of the types to be removed. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions , P_PAM_UNKNOWN_IDENTITY, P_PAM_DISASSOCIATED_TYPE , 
P PAM INVALID CREDENTIAL 



8.1.2.17 Method listTypesOf ldentity() 

List the types associated with the specified Identity. 

Returns a list containing all types associated with the specified Identity. A list with zero elements is returned if there are 
no types associated with the identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be looked up. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Returns 

TpP AMFQNameLi s t 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.2.18 Method hasType() 

Check if the specified identity has the named type associated with it. 

Returns true if an identity with the specified name has the named type associated with it, false otherwise. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be checked. 

typeName : in TpString 

Specifies the type to be checked for. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.2.19 Method getldentityAttributes() 

Return the attributes associated with the identity. If the identity type is not specified, all associated types are assumed to 
be of interest. 

The return value contains the list of specified attributes and their values. If the attributes parameter is an empty array, all 
attributes in the named identity are output. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity whose attributes are to be accessed. 

identityType : in TpString 

Specifies the type of the identity with which the required attributes are associated. Is optional. 

attributeNames : in TpStringList 

List of attributes of interest. Can be an empty array. 
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authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 

TpP AMAt tributeList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_UNKNOWN_TYPE, 
P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.1 .2.20 Method setldentityAttributes() 

Modify the attributes associated with the named Identity. The input may contain a subset of the attributes of the named 
type. Only the specified attributes will be modified and the rest will remain unchanged. If the type is unspecified, any 
associated type will be assumed. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity. 

identityType : in TpString 

Specifies the type of the identity for the operation. Is optional. 

attributes : in TpPAMAttributeList 

Contains the list of attributes and their values. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_UNKNOWN_TYPE, 
P_PAM_UNKNOWN_ATTRIBUTES , P_PAM_INVALID_CREDENTIAL 



8.1 .3 Interface Class IpPAMAgentManagement 

Inherits from: Iplnterface. 

The purpose of this interface is to manage agent (that models a hardware or software device) names, communication 
capabilities and sets of attributes associated with agents. An implementation may map these methods to operations on 
existing directories or databases. Some implementations may choose to provide a read-only access to the agent 
information. 

Data associated with an agent is captured in attributes associated with types. An implementation may map different 
type attributes to different underlying stores or directories. 

The names of agents within a namespace must be unique. 

This interface is meant for use by provisioning applications that establish and maintain agent names. 
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«lnterface» 
IpPAMAgentManagement 



createAgent (agentName : in TpPAMFQName, agentTypes : in TpStringList, autin Token : in 
TpPAMCredential) : void 

deleteAgent (agentName : in TpPAMFQName, autin Token : in TpPAMCredential) : void 

isAgent (agentName : in TpPAMFQName, autiiToken : in TpPAMCredential) : TpBoolean 

enableCapabilities (agentName : in TpPAMFQName, capabilities : in TpPAMCapabilityList, authToken : in 
TpPAMCredential) : void 

disableCapabilities (agentName : in TpPAMFQName, capabilities : in TpPAMCapabilityList, authToken : in 
TpPAMCredential) : void 

listEnabledCapabilities (agentName : in TpPAMFQName, authToken : in TpPAMCredential) : 
TpPAMCapabilityList 

listAIICapabilities (agentName : in TpPAMFQName, authToken : in TpPAMCredential) : 
TpPAMCapabilityList 

IsCapableQf (agentName : in TpPAMFQName, capability : in TpPAMCapability, authToken : in 
TpPAMCredential) : TpBoolean 

associateTypes (agentName : in TpPAMFQName, agentTypes : in TpStringList, authToken : in 
TpPAMCredential) : void 

disassociateTypes (agentName : in TpPAMFQName, agentTypes : in TpStringList, authToken : in 
TpPAMCredential) : void 

listTypesQfAgent (agentName : in TpPAMFQName, authToken : in TpPAMCredential) : TpStringList 

hasType (agentName : in TpPAMFQName, typeName : in TpString, authToken : in TpPAMCredential) : 
TpBoolean 

getAgentAttributes (agentName : in TpPAMFQName, agentType : in TpString, attributeNames : in 
TpStringList, authToken : in TpPAMCredential) : TpPAMAttributeList 

setAgentAttributes (agentName : in TpPAMFQName, agentType : in TpString, attributes : in 
TpPAMAttributeList, authToken : in TpPAMCredential) : void 



8.1.3.1 Method createAgentO 

Create an agent initialized with the speciiied capabilities. 

Parameters 

agentName : in TpPAMFQName 

Specifies the name of Agent to be created. 

agentTypes : in TpStringList 

Specifies the types of the Agent to be created. Can be an empty list. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Raises 

TpCommonExceptions, P_PAM_AGENT_EXISTS, P_PAM_UNKNOWN_TYPE, 
P PAM INVALID CREDENTIAL 



8.1 .3.2 Method deleteAgentQ 

Delete the specified Agent and all related data from the system. 

Parameters 

agentName : in TpPAMFQName 

Specifies the name of Agent to be created. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_INVALID_CREDENTIAL 



8.1.3.3 Method isAgentO 

Check if the specified agent exists. 

Returns true if an agent with the specified name exists, false otherwise. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent to be checked. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1.3.4 Method enableCapabilities() 

Enable the specified capabilities of the agent. 
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Parameters 

agentName : in TpPAMFQName 

Specifies the Agent. 

capabilities : in TpPAMCapabilityList 

Specifies the capabilities to be enabled. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_INVALID_CREDENTIAL 



8.1 .3.5 Method disableCapabilities() 

Remove the specified capabilities from the Agent. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent. 

capabilities : in TpPAMCapabilityList 

Specifies the communication mode to be disabled. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_NO_CAPABILITY, 
P PAM INVALID CREDENTIAL 



8.1.3.6 Method listEnabledCapabilities() 

List the enabled capabilities for the specified Agent. 

Returns the list of enabled capabilities for the Agent. Returns an empty list if no enabled capabilities exist for the agent. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent whose capabilities are to be listed. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Returns 
TpPAMCapabilityList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_INVALID_CREDENTIAL 



8.1.3.7 Method listAIICapabilities() 

List the capabilities for the specified Agent. 

Returns the Ust of capabilities for the Agent. Returns an empty list if no capabilities exist for the agent. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent whose capabilities are to be listed. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMCapabilityList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_INVALID_CREDENTIAL 



8.1.3.8 Method isCapableOfQ 

Check if an agent has a particular capability that is currently enabled. 
Returns true if the agent has the specified capability, false otherwise. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent to be checked. 

capability : in TpPAMCapability 

Capability to be checked. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Returns 
TpBoolean 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_INVALID_CREDENTIAL 



8.1.3.9 Method associateTypesQ 

Associate an agent instance with the specified types. 

Parameters 

agentName : in TpPAMFQName 

Specifies the name of Agent. 

agentTypes : in TpStringList 

Specifies the types of the Agent to be associated. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_UNKNOWN_TYPE , 
P_PAM_TYPE_ASSOCIATED , P_PAM_INVALID_CREDENTIAL 



8.1 .3.10 Method disassociateTypesQ 

Remove the association of a type with an agent instance. The definition of the type itself remains unaffected and the 
types may continue to be associated with other agents. 

Parameters 

agentName : in TpPAMFQName 

Specifies the agent. 

agentTypes : in TpStringList 

Specifies the names of the types to be removed. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_DISASSOCIATED_TYPE, 
P PAM INVALID CREDENTIAL 
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8.1 .3.1 1 Method listTypesOfAgentQ 

List the types associated with the specified agent. 

Returns the list containing all types associated with the specified agent. An empty list is returned if there are no types 
associated with the agent. 

Parameters 

agentName : in TpPAMFQName 

Specifies the agent to be looked up. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_INVALID_CREDENTIAL 



8.1.3.12 Method hasTypeO 

Check if the specified agent has the named type associated with it. 

Returns true if an agent with the specified name has the named type associated with it. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent to be checked. 

typeName : in TpString 

Specifies the type to be checked for. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_INVALID_CREDENTIAL 



8.1 .3.13 Method getAgentAttributes() 

Return the attributes associated with the agent. If the type is not specified, all associated types are assumed. 
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Return value contains the list of specified attributes and their values. If the attributes parameter is an empty list, all 
attributes in the named agent are returned. 

Parameters 

agentName : in TpPAMFQName 

Specifies the agent. 

agentType : in TpString 

Specifies the type of interest. Is optional. 

attributeNames : in TpStringList 

List of attributes of interest. Can be an empty list. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAttributeList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_UNKNOWN_TYPE , 
P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.1.3.14 Method setAgentAttributesQ 

Modify the attributes associated with the named agent. The input may contain a subset of the attributes of the named 
type. Only the specified attributes will be modified and the rest will remain unchanged. 

Parameters 

agentName : in TpPAMFQName 

Specifies the agent. 

agentType : in TpString 

Specifies the type of interest. Is optional. 

attributes : in TpPAMAttributeList 

Contains the list of attributes and their values. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_UNICNOWN_TYPE , 
P_PAM_UNKNOWN_ATTRIBUTES , P_PAM_INVALID_CREDENTIAL 
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8.1 .4 Interface Class IpPAMAgentAssignment 

Inherits from: Iplnterface. 

The purpose of this interface is to manage the relationship between identities and the agents assigned to them. The 
identities inherit capabilities from the assignments of agents. 

The implementation must maintain the integrity of the relationship between identities and agents across changes to 
both identities and agents. Implementations may map these methods to operations on existing directories and databases. 
Some implementations may provide a read-only access to this interface. 

This interface is meant for use by provisioning applications that establish and maintain association of agents with 
identities. 



«lnterface» 
IpPAMAgentAssignment 



assignAgent (identity : in TpPAMFQName, agentName : in TpPAMFQName, authToken : in 
TpPAMCredential) : void 

unassignAgent (identity : in TpPAMFQName, agentName : in TpPAMFQName, autin Token : in 
TpPAMCredential) : void 

listAssignedAgents (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQNameList 

listAssociatedldentitiesQfAgent (agentName : in TpPAMFQName, authToken : in TpPAMCredential) : 
TpPAMFQNameList 

listAssignedAgentsByCapability (identity : in TpPAMFQName, capability : in TpPAMCapability, authToken : 
in TpPAMCredential) : TpPAMFQNameList 

listCapabilitiesQfldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : 
TpPAMCapabilityList 

IsidentityCapableQf (identity : in TpPAMFQName, capability : in TpPAMCapability, authToken : in 
TpPAMCredential) : TpBoolean 



8.1.4.1 Method assignAgentO 

Assign an existing agent to an existing identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity to assign the agent to. 

agentName : in TpPAMFQName 

Specifies the Agent. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_UNKNOWN_AGENT , 
P PAM INVALID CREDENTIAL 



8.1.4.2 Method unassignAgentO 

Unassign an agent from an existing identity. In effect, this deletes an existing relationship between an agent and an 
identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity to assign the agent to. 

agentName : in TpPAMFQName 

Specifies the Agent. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_UNKNOWN_AGENT , 
P_PAM_UNKNOWN_ASSIGNMENT, P_PAM_INVALID_CREDENTIAL 



8.1.4.3 Method listAssignedAgents() 

List the Agents assigned to an identity. 

Returns the list of agent names assigned to the identity. An empty list is returned if no agents are assigned to the 
identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 

TpP AMFQNameLi s t 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 
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8.1.4.4 Method listAssociatedldentitiesOfAgent() 

List the identities that have the specified agent assigned to them. 

Returns the list of identities that have been assigned the specified agent. Empty list is returned if no identities have been 
assigned this agent. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 

TpP AMFQNameLi s t 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_INVALID_CREDENTIAL 



8.1.4.5 Method listAssignedAgentsByCapabilityO 

List the Agents assigned to an identity that match the specified capability. 

Returns the list of agent names with the specified capability. An empty list is returned no agents are found. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

capability : in TpPAMCapability 

Specifies the capability of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMFQNameList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.4.6 Method listCapabilitiesOfldentity() 

List the capabilities of an identity that it derives from its assigned Agents. 

Returns the hst of the identity's capabilities. Returns an empty list if no capabilities exist. 
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Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMCapabilityList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.4.7 Method isldentityCapableOf() 

Check if an identity has the specified capabiHty derived from one or more agents assigned to it. 
Returns true if the identity has this capabiUty, false otherwise. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

capability : in TpPAMCapability 

Identifies the capabiHty to check for. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1 .5 Interface Class IpPAMIdentityTypeManagement 

Inherits from: Iplnterface. 

This clause describes the programmatic interface to define the type schema for identities specifying the attributes 
associated with the type. These types can then be assigned to identities. PAM implementations may provide a set of pre- 
defined types. Identity type names and agent type names are in the same namespace and hence must be uniquely 
defined across both identities and agents. The attributes for identity types and agent types are in two different 
namespaces and hence an attribute name may be re-used with different characteristics for identities and agents. 
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«lnterface» 
IpPAMIdentityTypeManagement 



createldentityAttribute (pAttribute : in TpPAMAttributeDef, authToken : in TpPAMCredential) : void 

deleteldentityAttribute (attributeName : in TpString, autinToken : in TpPAMCredential) : void 

getldentityAttributeDefinition (attributeName : in TpString, autin Token : in TpPAMCredential) : 
TpPAMAttributeDef 

listAllldentityAttributes (authToken : in TpPAMCredential) : TpStringList 

createldentityType (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

deleteldentityType (typeName : in TpString, authToken : in TpPAMCredential) : void 

listldentity Types (authToken : in TpPAMCredential) : TpStringList 

addldentityTypeAttributes (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

removeldentityTypeAttributes (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

listldentityTypeAttributes (typeName : in TpString, authToken : in TpPAMCredential) : TpStringList 



8.1.5.1 Method createldentityAttribute() 

Create a definition of an identity attribute to specify its name and type. 

Parameters 

pAttribute : in TpPAMAttributeDef 

Specifies the attribute to be created. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_ATTRIBUTE_EXISTS, P_PAM_INVALID_CREDENTIAL 



8.1 .5.2 Method deleteldentityAttributeQ 

Delete the definition of an identity attribute. 

Parameters 

attributeName : in TpString 

Specifies the attribute to be deleted. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 
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Raises 

TpCommonExceptions, P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.1 .5.3 Method getldentityAttributeDefinitionQ 

Get the definition for the specified identity attribute. 
Returns the definition of the specified attribute. 

Parameters 

attributeName : in TpString 

Specifies the attribute. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 

TpP AMAt t r ibut eD e f 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.1.5.4 Method listAllldentityAttributes() 

List all known identity attributes. 

Returns the list of attribute names defined so far. An empty array if no attributes have been defined. 

Parameters 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1.5.5 Method createldentityTypeQ 

Specify a label as the name of an identity type. 
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Parameters 

typeName : in TpString 

Specifies the name of the type to be created. 

attributeNames : in TpStringList 

Specifies the hst of attributes to be added. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_TYPE_EXISTS, P_PAM_UNKNOWN_ATTRIBUTE , 
P PAM INVALID CREDENTIAL 



8.1 .5.6 Method deleteldentityType() 

Delete a label as the name of an identity type. All identities that have this type are no longer associated with this type 
and consequently will no longer will have any attributes associated with this type. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_INVALID_CREDENTIAL 



8.1.5.7 Method listldentityTypes() 

List all known identity types. 

Returns the list of known identity types. An empty array if no identity types have been defined. 

Parameters 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 
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Returns 
TpStringList 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1.5.8 Method addldentityTypeAttributes() 

Add attribute definitions to the schema of an identity type that has already been defined. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

attributeNames : in TpStringList 

List of attributes to be added to this type. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_ATTRIBUTE_EXISTS, 
P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.1.5.9 Method removeldentityTypeAttributes() 

Delete attribute definitions from the schema of an identity type that has already been defined. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

attributeNames : in TpStringList 

Specifies the list of attributes to be deleted. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_UNKNOWN_ATTRIBUTE , 
P PAM INVALID CREDENTIAL 
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8.1.5.10 Method listldentityTypeAttributes() 

List all attributes of an identity type. 

Returns the list of attribute definitions for the named type. An empty array if no attributes have been defined for this 
type. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_INVALID_CREDENTIAL 



8.1 .6 Interface Class IpPAMAgentTypeManagement 

Inherits from: Iplnterface. 

This clause describes the programmatic interface to define the type schema for agents specifying the attributes 
associated with the type. These types can then be assigned to agents. PAM implementations may provide a set of pre- 
defined types. Identity type names and agent type names are in the same namespace and hence must be uniquely 
defined across both identities and agents. The attributes for identity types and agent types are in two different 
namespaces and hence an attribute name may be re-used with different characteristics for identities and agents. 
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«lnterface» 
IpPAMAgentTypeManagement 



createAgentAttribute (pAttribute : in TpPAMAttributeDef, authToken : in TpPAMCredential) : void 

deleteAgentAttribute (attributeName : in TpString, autin Token : in TpPAMCredential) : void 

getAgentAttributeDefinition (attributeName : in TpString, autin Token : in TpPAMCredential) : 
TpPAMAttributeDef 

listAIIAgentAttributes (authToken : in TpPAMCredential) : TpStringList 

createAgentType (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

deleteAgentType (typeName : in TpString, authToken : in TpPAMCredential) : void 

listAgentTypes (authToken : in TpPAMCredential) : TpStringList 

addAgentTypeAttributes (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

removeAgentTypeAttributes (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

listAgentTypeAttributes (typeName : in TpString, authToken : in TpPAMCredential) : TpStringList 



8.1.6.1 Method createAgentAttribute() 

Create a definition of an Agent attribute to specify its name and type. 

Parameters 

pAttribute : in TpPAMAttributeDef 

Specifies the attribute to be created. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_ATTRIBUTE_EXISTS, P_PAM_INVALID_CREDENTIAL 



8.1.6.2 Method deleteAgentAttributeQ 

Delete the definition of an Agent attribute. 

Parameters 

attributeName : in TpString 

Specifies the attribute to be deleted. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 
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Raises 

TpCommonExceptions, P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.1 .6.3 Method getAgentAttributeDefinitionQ 

Get the definition for the specified Agent attribute. 
Returns the definition of the specified attribute. 

Parameters 

attributeName : in TpString 

Specifies the attribute. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 

TpP AMAt t r ibut eD e f 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.1.6.4 Method listAIIAgentAttributes() 

List all known Agent attributes. 

Returns the list of attribute names defined so far. An empty array if no attributes have been defined. 

Parameters 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1 .6.5 Method createAgentType() 

Specify a label as the name of an Agent type. 
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Parameters 

typeName : in TpString 

Specifies the name of the type to be created. 

attributeNames : in TpStringList 

Specifies the hst of attributes to be added. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_TYPE_EXISTS, P_PAM_UNKNOWN_ATTRIBUTE , 
P PAM INVALID CREDENTIAL 



8.1 .6.6 Method deleteAgentType() 

Delete a label as the name of an Agent type. All identities that have this type are no longer associated with this type and 
consequently will no longer will have any attributes associated with this type. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_INVALID_CREDENTIAL 



8.1.6.7 Method listAgentTypesQ 

List all known Agent types. 

Returns the list of known Agent types. An empty array if no Agent types have been defined. 

Parameters 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 
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Returns 
TpStringList 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1 .6.8 Method addAgentTypeAttributes() 

Add attribute definitions to the schema of an Agent type that has already been defined. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

attributeNames : in TpStringList 

List of attributes to be added to this type. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_ATTRIBUTE_EXISTS, 
P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.1.6.9 Method removeAgentTypeAttributesQ 

Delete attribute definitions from the schema of an Agent type that has already been defined. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

attributeNames : in TpStringList 

Specifies the list of attributes to be deleted. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_UNKNOWN_ATTRIBUTE , 
P PAM INVALID CREDENTIAL 
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8.1.6.10 Method listAgentTypeAttributes() 

List all attributes of an Agent type. 

Returns the list of attributes for the named type. An empty array if no attributes have been defined for this type. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_INVALID_CREDENTIAL 



8.1 .7 Interface Class IpPAMCapabilityManagement 

Inherits from: Iplnterface. 

This clause describes the programmatic interface to define capability names. 

Capabilities are names that define a property of an agent for which presence data may exist. Examples are voice, IM, 
SMS, WAP, etc. Agents can be assigned capabilities. Identities inherit capabilities from agents but cannot be directly 
assigned capabilities. Each capability is defined with an associated set of attributes. The attributes for each capability 
exist in their own namespace and hence an attribute name may be re-used with different characteristics across 
capabilities. 
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«lnterface» 
IpPAMCapabilityManagement 



createCapabilityAttribute (pAttribute : in TpPAMAttributeDef, authToken : in TpPAMCredential) : void 

deleteCapabilityAttribute (attributeName : in TpString, autin Token : in TpPAMCredential) : void 

getCapabilityAttributeDefinition (attributeName : in TpString, autliToken : in TpPAMCredential) : 
TpPAMAttributeDef 

listAIICapabilityAttributes (authToken : in TpPAMCredential) : TpStringList 

createCapability (capabilityName : in TpPAMCapability, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

deleteCapability (capabilityName : in TpPAMCapability, authToken : in TpPAMCredential) : void 

listCapabilities (authToken : in TpPAMCredential) : TpPAMCapabilityList 

addCapabilityAttributes (capabilityName : in TpPAMCapability, attributeNames : in TpStringList, authToken : 
in TpPAMCredential) : void 

removeCapabilityAttributes (capabilityName : in TpPAMCapability, attributeNames : in TpStringList, 
authToken : in TpPAMCredential) : void 

listCapabilityAttributes (capabilityName : in TpPAMCapability, authToken : in TpPAMCredential) : 
TpStringList 

assignCapabilitiesToType (agentType : in TpString, capabilities : in TpPAMCapabilityList, authToken : in 
TpPAMCredential) : void 

unassignCapabilitiesFromType (agentType : in TpString, capabilities : in TpPAMCapabilityList, authToken : 
in TpPAMCredential) : void 

listCapabilitiesOfType (agentType : in TpString, authToken : in TpPAMCredential) : TpPAMCapabilityList 



8.1.7.1 Method createCapability Attribute() 

Create a definition of a Capability attribute to specify its name and type. 

Parameters 

pAttribute : in TpPAMAttributeDef 

Specifies the attribute to be created. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_ATTRIBUTE_EXISTS, P_PAM_INVALID_CREDENTIAL 



8.1 .7.2 Method deleteCapabilityAttribute() 

Delete the definition of a Capability attribute. 
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Parameters 

attributeName : in TpString 

Specifies the attribute to be deleted. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.1 .7.3 Method getCapabilityAttributeDefinitionQ 

Get the definition for the specified Capability attribute. 
Returns the definition of the specified attribute. 

Parameters 

attributeName : in TpString 

Specifies the attribute. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 

TpP AMAt t r ibut eD e f 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.1.7.4 Method listAIICapabilityAttributes() 

List all known Capability attributes. 

Returns the list of attribute names defined so far. An empty array if no attributes have been defined. 

Parameters 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 
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Returns 
TpStringList 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1.7.5 Method createCapabilityO 

Specify a label as the name of a Capability type. 

Parameters 

capabilityName : in TpPAMCapability 

Specifies the name of the type to be created. 

attributeNames : in TpStringList 

Specifies the list of attributes to be added. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_TYPE_EXISTS, P_PAM_UNKNOWN_ATTRIBUTE , 
P PAM INVALID CREDENTIAL 



8.1 .7.6 Method deleteCapability() 

Delete a label as the name of a Capability. All agents that have this type are no longer associated with this type and 
consequently will no longer will have any attributes associated with this type. 

Parameters 

capabilityName : in TpPAMCapability 

Specifies the name of the type. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_INVALID_CREDENTIAL 



8.1.7.7 Method listCapabilitiesQ 

List all known Capability types. 
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Returns the list of known Capability types. An empty array if no Capability types have been defined. 

Parameters 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 
TpPAMCapabilityList 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1.7.8 Method addCapabilityAttributes() 

Add attribute definitions to the schema of a capability that has already been defined. 

Parameters 

capabilityName : in TpPAMCapability 

Specifies the name of the type. 

attributeNames : in TpStringList 

List of attributes to be added to this type. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_ATTRIBUTE_EXISTS, 
P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.1.7.9 Method removeCapabilityAttributes() 

Delete attribute definitions from the schema of a Capability that has already been defined. 

Parameters 

capabilityName : in TpPAMCapability 

Specifies the name of the type. 

attributeNames : in TpStringList 

Specifies the list of attributes to be deleted. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 
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Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE , P_PAM_UNKNOWN_ATTRIBUTE , 
P PAM INVALID CREDENTIAL 



8.1.7.10 Method listCapabilityAttributes() 

List all attributes of a capability. 

Returns the list of attributes for the named Capability. An empty array if no attributes have been defined for this 
capability. 

Parameters 

capabilityName : in TpPAMCapability 

Specifies the name of the type. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_INVALID_CREDENTIAL 



8.1 .7.1 1 Method assignCapabilitiesToType() 

Assign capabilities to agent type. 

Parameters 

agentType : in TpString 

Name of an agent type. 

capabilities : in TpPAMCapabilityList 

Specifies the list of capabihties to be associated. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_UNKNOWN_CAP ABILITY, 
P PAM INVALID CREDENTIAL 
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8.1.7.12 Method unassignCapabilitiesFromType() 

Unassign capabilities from an agent type. 

Parameters 

agentType : in TpString 

Name of an agent type. 

capabilities : in TpPAMCapabilityList 

Specifies the list of capabilities to be disassociated. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCoinmonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_UNKNOWN_CAPABILITY, 
P PAM INVALID CREDENTIAL 



8.1.7.13 Method listCapabilitiesOfType() 

List capabilities assigned to an agent type. 

Returns the hst of capabilities assigned to the agent type. 

Parameters 

agentType : in TpString 

Name of an agent type. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMCapabilityList 

Raises 

TpCoinmonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_INVALID_CREDENTIAL 

8.2 PAM Access SCF Interface Classes 

This service consists of the presence and availability query and update interfaces. 

8.2.1 Interface Class IpPAMPresenceAvailabilityManager 

Inherits from: IpService. 

The purpose of this interface is to supply the various interfaces available in this service to the application and to provide 
the authentication credentials. This interface is the only discoverable interface from the framework. 

All PAM methods optionally use an authentication token as a parameter since the outcome of the operations may 
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depend on the entity requesting the operation. To enable this, the getAuthToken() method is used to obtain an 
implementation dependent token. An application that has authenticated itself with the OS A framework, can get an 
authentication token for itself Alternatively, if the application is requesting PAM operations on behalf of multiple 
entities, authentication tokens may be requested for each such entity after providing any available data about the asker. 
These tokens can then be used repeatedly for operations within a session without further need to identify the asker. 



«lnterface» 
IpPAMPresenceAvailabilityManager 



getAuthloken (askerData : in TpAttributeList) : TpPAMCredential 

obtainlnterface (interfaceName : in TpPAMPresenceAvailabilitylnterfaceName) : IplnterfaceRef 

«new» getAccessControl (identity : in TpPAMFQName, autin Token : in TpPAMCredential) : 
TpPAMAccessControl Data 

«new» setAccessControl (identity : in TpPAMFQName, operation : in TpPAMPreferenceOp, 
newAccessControl : in TpPAMAccessControlData, autiiToken : in TpPAMCredential) : void 

«new» activateService (identity : in TpPAMFQName, authToken : in TpPAMCredential) : void 

«new» deactivateService (identity : in TpPAMFQName, authToken : in TpPAMCredential) : void 

«new» isActiveldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpBoolean 



8.2.1 .1 Method getAuthloken () 

Get an authentication token for access to the interface methods. 

Returns an implementation-dependent authentication credential that can be verified. 

Parameters 

askerData : in TpAttributeList 

Specifies information about the asker. Can be an empty array. The exact attributes in this list are dependent on the 
application. PAM reserves the attribute "name" with type TpPAMFQName to contain the identity of the asker if known. 

Returns 
TpPAMCredential 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.2.1.2 Method obtain InterfaceQ 

Obtain available interfaces from the service. The valid parameters for this method can be obtained from the service 
property P_OBTAIN ABLEJNTERFACES . 

Returns the requested interface. 
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Parameters 

interfaceName : in TpPAMPresenceAvailabilitylnterfaceName 

Specifies the name of the required interface. 

Returns 
IpInterfaceRef 

Raises 

TpCommonExceptions , P_PAM_UNAVAILABLE_INTERFACE 

8.2.1 .3 Method «new» getAccessControl() 

Get the access control associated with the data belonging to an identity. The data associated with an identity includes 
the static and dynamic attributes of an identity as well as data about agents associated with an identity. 

This method should be used in conjunction with the setAccessControl method. 

Returns the access control if previously specified for the identity. Is null if there is no access control associated. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAccessControlData 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.2.1 .4 Method «new» setAccessControl() 

Set the access controls for the data associated with the specified identity. If the identity is Null, the access control is set 
for all identities (if authorized to do so). The data associated with an identity includes the static and dynamic attributes 
of an identity as well as data about agents associated with an identity. 

Any existing access control will be modified based on the operation. 

If the new access control is specified as Null for replace operation , an existing access control will be removed. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

operation : in TpPAMPreferenceOp 

Specifies the operation to be performed with the specified preference. 
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newAccessControl : in TpPAMAccessControlData 

Specifies the access controls to add. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.2.1 .5 Method «new» activateService() 

Activate the service for the specified identity. If the identity is null, activate the service for ALL identities. The method 
succeeds if the service is already activated for the specified identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Can be NULL (empty string). 

authToken : in TpPAMCredential 

of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNICNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.2.1 .6 Method «new» deactivateService() 

Deactivate the service for the specified identity. If the identity is null, deactivate the service for ALL identities. The 
method succeeds if the service is already deactivated for the specified identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Can be NULL (empty string). 

authToken : in TpPAMCredential 

of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.2.1 .7 Method «new» isActiveldentity() 

Check if the service is active for the specified identity. 

Returns true if the service is active for that identity, false otherwise. 
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Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Cannot be NULL (empty string). 

authToken : in TpPAMCredential 

of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.2.2 Interface Class IpPAMIdentityPresence 

Inherits from: Iplnterface. 

The purpose of this interface is to maintain the dynamic presence information of identity. 

The underlying implementations may optimize the storage for this dynamic data rather than rely on a general- 
purpose directory or database when performance is an issue. Presence information for identities may be explicitly 
registered are may be implicitly derived from the underlying networks or presence information from agents associated 
with the identity. 

This interface is meant for use by applications that register and/or maintain dynamic presence information 
associated with identities and accessible without the privacy or other controls established by availability preferences. 
These applications may not be aware of the name and the types of agents associated with the identity. 

The presence information can be explicitly registered using the interface or the presence may come from 
information implicitly derived (e.g., using presence information of agents associated with the identity). 



«lnterface» 
IpPAMIdentityPresence 



setldentityPresence (identity : in TpPAMFQName, identityType : in TpString, attributes : in 
TpPAMAttributeList, autliToken : in TpPAMCredential) : void 

setldentityPresenceExpiration (identity : in TpPAMFQName, identityType : in TpString, attributeNames : in 
TpStringList, expiresin : in TpPAMTimelnterval, authToken : in TpPAMCredential) : void 

getldentityPresence (identity : in TpPAMFQName, identityType : in TpString, attributeNames : in 
TpStringList, authToken : in TpPAMCredential) : TpPAMAttributeList 



8.2.2.1 Method setldentityPresence() 

Set identity's dynamic attributes. 
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Parameters 

identity : in TpPAMFQName 

Specifies the identity. 

identityType : in TpString 

Specifies the type of the identity. 

attributes : in TpPAMAttributeList 

Specifies the attributes to set. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_UNKNOWN_TYPE, 
P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.2.2.2 Method setldentityPresenceExpiration() 

Set or reset the expiration of an identity's named presence attributes. If the attributeNames parameter is an empty list, 
the expiration time of all attributes defined for the identity will have their expiration time changed. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity. 

identityType : in TpString 

Specifies the type of the identity. 

attributeNames : in TpStringList 

Specifies the names of the attributes. Can be an empty list. 

expires In : in TpPAMTime Interval 

Specifies the number of seconds until the attributes expire. A value of -1 indicates no expiration. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_UNKNOWN_TYPE, 
P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.2.2.3 Method getldentityPresenceQ 

Retrieve presence attributes associated with an identity. 
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Return value contains the requested attributes of the named capability. If the attributes parameter is an empty array, all 
attributes of the named profile are included. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity. 

identityType : in TpString 

Specifies the type of the identity. 

attributeNames : in TpStringList 

Specifies the attributes of interest. Can be an empty list. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAttributeList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_UNKNOWN_TYPE , 
P_PAM_UNKNOWN_ATTRIBUTE , P_PAM_INVALID_CREDENTIAL 



8.2.3 Interface Class IpPAMAvailability 

Inherits from: Iplnterface. 

The purpose of the interface is to: 

- Manage the preferences specified for the availability of an identity and, to 

- Query for the availability of identities for specific capabilities. 

- Query for attributes of interest from an identity. 

Simple implementations may equate the availability of identities to presence of their agents with available 
status. More complex implementations may consider, in addition, the preferences specified for availability as well as the 
attributes of the entity asking for availability. 

The queries for availability are done for a specified context. A context is a set of attributes describing the situation 
for which availability is requested. PAM specifies one pre-defined context - Communication. The Communication 
context is used for availability for a specific mode of communication. Applications and PAM implementations may 
extend and provide additional contexts such as availability at a particular location, availability for a specific mode of 
communication at a given location, etc. The context information also includes any information about the asker as may 
be provided by the asker. 

The specification defines two types of preference mechanisms although implementations may support additional 
mechanisms. The first mechanism consists of access control lists that specify identities that are allowed/denied to access 
information about the identity whose preference is being set. The second mechanism allow for an external application 
interface to be specified to check for access control as well as to compute availability. 
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«lnterface» 
IpPAMAvailability 



getAvailability (identity : in TpPAMFQName, pamContext : in TpPAMContext, attributeNames : in 
TpStringList, autin Token : in TpPAMCredential) : TpPAMAvailabilityProfileList 

getPreference (identity : in TpPAMFQName, pamContext : in TpPAMContext, autin Token : in 
TpPAMCredential) : TpPAMPreferenceData 

setPreference (identity : in TpPAMFQName, pamContext : in TpPAMContext, operation : in 

TpPAMPreferenceQp, newPreference : in TpPAMPreferenceData, autin Token : in TpPAMCredential) 
void 



8.2.3.1 Method getAvailability() 

Get the availability for an identity for a given context. 

All contexts may optionally include an asker profile. Although PAM applications may decide what attributes to include 
in an asker profile, PAM implementations should not require such attributes to be present. The implementations should 
leave it to the availability computations to decide the availability based on the (partial) information provided. 

It is also up to the availability computation to decide on the trustworthiness of the asker profile information based on the 
application, the credentials of the entity asking for availability and/or the credentials, if any, of the entity accessing the 
interface. 

Returns a value containing a list of attributes as available to the asker in the requested context. If no information is 
available to the asker an empty list is returned. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity for which the availability is being requested. 

pamContext : in TpPAMContext 

Specifies the context for which the availability is requested. 

attributeNames : in TpStringList 

Specifies the attributes of interest. Can be an empty list to indicate all attributes. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAvailabilityProfileList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 
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8.2.3.2 Method getPreference() 

Get the availability preferences of an identity for the specified communication mode. 
This method should be used in conjunction with the setPreference method. 

Returns the preference for the named context if previously specified for the identity. Is null if there are no preferences 

associated. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

pamContext : in TpPAMContext 

Specifies the context for which the preferences are requested. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMPreferenceData 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.2.3.3 Method setPreferenceQ 

Set the availability preferences for the specified identity for the specified context. If the identity is Null, the preference 
is set for all identities (if authorized to do so). 

The existing preference will be modified based on the operation. 

If the new preference is specified as Null for replace operation , any existing preferences for the specified context will 
be removed. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity with which the preference will be associated. 

pamContext : in TpPAMContext 

Specifies the capability to which this preference applies. 

operation : in TpPAMPreferenceOp 

Specifies the operation to be performed with the specified preference. 

newPreference : in TpPAMPreferenceData 

Specifies the availability preference to add. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.2.4 Interface Class IpAppPAMPreferenceCheck 

Inherits from: Iplnterface. 

The purpose of this interface is to provide methods to be called by the PAM service to check for access control or to 
compute availability using an implementation provided by an application. Instances of this interface are registered using 
the setPreferenceO method in the availability management interface. 



«lnterface» 
IpAppPAMPreferenceCheck 



computeAvailability (identity : in TpPAMFQName, pamContext : in TpPAMContext, attributeNames : in 
TpStringList, autin Token : in TpPAMCredential) : TpPAMAvailabilityProfileList 



8.2.4.1 Method computeAvailability() 

Compute the availability for an identity for a given context. The data provided is the same as the data provided for the 
getAvailability call. The application implementing this interface uses the identity presence interface to get the current 
presence data and maintains its own user preferences to compute the availability. 

Returns a value containing a list of attributes as available to the asker in the requested context. If no information is 
available to the asker an empty list is returned. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity for which the availability is being requested. 

pamContext : in TpPAMContext 

Specifies the context for which the availability is requested. 

attributeNames : in TpStringList 

Specifies the attributes of interest. Can be an empty list to indicate all attributes. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAvailabilityProfileList 
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8.3 PAM Event SCF Interface Classes 

This service contains an interface for registering for notifications for events that occur within the PAM service. 

8.3.1 Interface Class IpPAMEventManager 

Inherits from: IpService. 

The purpose of this interface is to supply the various interfaces available in this service to the application and to provide 
the authentication credentials. This interface is the only discoverable interface from the framework. 

All PAM methods use an authentication token as a parameter since the outcome of the operations may depend on 
the entity requesting the operation. To enable this, the getAuthToken() method is used to obtain an implementation 
dependent token. An application that has authenticated itself with the OSA framework, can get an authentication token 
for itself. Alternatively, if the application is requesting PAM operations on behalf of multiple entities, authentication 
tokens may be requested for each such entity after providing any available data about the asker. These tokens can then 
be used repeatedly for operations within a session without further need to identify the asker. 



«lnterface» 
IpPAMEventManager 



getAuthToken (askerData : in TpAttributeList) : TpPAMCredential 

obtainlnterface (interfaceName : in TpPAMEventlnterfaceName) : IplnterfaceRef 

«new» getAccessControl (identity : in TpPAMFQName, autin Token : in TpPAMCredential) : 
TpPAMAccessControl Data 

«new» setAccessControl (identity : in TpPAMFQName, operation : in TpPAMPreferenceOp, 
newAccessControl : in TpPAMAccessControlData, authToken : in TpPAMCredential) : void 

«new» activateService (identity : in TpPAMFQName, authToken : in TpPAMCredential) : void 

«new» deactivateService (identity : in TpPAMFQName, authToken : in TpPAMCredential) : void 

«new» isActiveldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpBoolean 



8.3.1 .1 Method getAuthToken () 

Get an authentication token for access to the interface methods. 

Returns an implementation-dependent authentication credential that can be verified. 

Parameters 

askerData : in TpAttributeList 

Specifies information about the asker. Can be an empty array. The exact attributes in this list are dependent on the 
application. PAM reserves the attribute "name" with type TpPAMFQName to contain the identity of the asker if known. 
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Returns 
TpPAMCredential 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.3.1.2 Method obtain InterfaceO 

Obtain available interfaces from the service. The valid parameters for this method can be obtained from the service 
property P_OBTAINABLE_INTERFACES . 

Returns the requested interface. 

Parameters 

interfaceName : in TpPAMEventlnterfaceName 

Specifies the name of the required interface. 

Returns 
IpInterfaceRef 

Raises 

TpCommonExceptions , P_PAM_UNAVAILABLE_INTERFACE 



8.3.1 .3 Method «new» getAccessControl() 

Get the access control associated with the data belonging to an identity. The data associated with an identity includes 
the static and dynamic attributes of an identity as well as data about agents associated with an identity. 

This method should be used in conjunction with the setAccessControl method. 

Returns the access control if previously specified for the identity. Is null if there is no access control associated. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 



£75/ 



3GPP TS 29.1 98-1 4 version 6.3.1 Release 6 75 ETSI TS 1 29 1 98-1 4 V6.3.1 (2006-07) 

Returns 
TpPAMAccessControlData 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.3.1 .4 Method «new» setAccessControl() 

Set the access controls for the data associated with the specified identity. If the identity is Null, the access control is set 
for all identities (if authorized to do so). The data associated with an identity includes the static and dynamic attributes 
of an identity as well as data about agents associated with an identity. 

Any existing access control will be modified based on the operation. 

If the new access control is specified as Null for replace operation , an existing access control will be removed. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

operation : in TpPAMPreferenceOp 

Specifies the operation to be performed with the specified preference. 

newAccessControl : in TpPAMAccessControlData 

Specifies the access controls to add. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.3.1 .5 Method «new» activateService() 

Activate the service for the specified identity. If the identity is null, activate the service for ALL identities. The method 
succeeds if the service is already activated for the specified identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Can be NULL (empty string). 

authToken : in TpPAMCredential 

of the entity who wishes to do this operation. 
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Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.3.1 .6 Method «new» deactivateService() 

Deactivate the service for the specified identity. If the identity is null, deactivate the service for ALL identities. The 
method succeeds if the service is already deactivated for the specified identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Can be NULL (empty string). 

authToken : in TpPAMCredential 

of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.3.1 .7 Method «new» isActiveldentity() 

Check if the service is active for the specified identity. Returns true if the service is active for that identity, false 
otherwise. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Cannot be NULL (empty string). 

authToken : in TpPAMCredential 

of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.3.2 Interface Class IpAppPAMEventHandler 

Inherits from: Iplnterface. 

This is the interface that a client application must implement and register with the Event Service in order to be notified 
of events. 
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«lnterface» 
IpAppPAMEventHandler 



eventNotify (eventID : in TpPAMEventID, eventlnfo : in TpPAMNotificationlnfoList) : void 
eventNotifyErr (eventID : in TpPAMEventID, errorlnfo : in TpPAMErrorlnfo) : void 



8.3.2.1 Method eventNotifyQ 

Notify the occurrence of an event. The implementations will not attempt to re-notify on failure. 

Parameters 

eventID : in TpPAMEventID 

Specifies a prior event registration ID. 

eventlnfo : in TpPAMNotificationlnfoList 

Contains the data about the events that occurred. 



8.3.2.2 Method eventNotifyErr() 

Notify an error in the event reporting. The error may concern all assignments, one whole assignment or a part of it. An 
eventNotify is sent after the error condition has passed away unless the event has been subsequently deregistered. Re- 
registration may only be needed in fatal system error cases. Note that in normal operation unavailable or protected 
pieces of presence information are delivered by the normal reporting methods instead of an error method. 

Parameters 

eventID : in TpPAMEventID 

Specifies a prior event registration ID. 

errorlnfo : in TpPAMErrorlnfo 

Contains the data relating to the error. 



8.3.3 Interface Class IpPAMEventHandler 

Inherits from: Iplnterface. 

The purpose of this interface is to manage the registrations of interest in events and the registration of client interfaces 
for subsequent notification. All notifications in the present document are to be sent after the corresponding event has 
occurred and are asynchronous. An application must first register a notification interface with the service. It can then 
register interest in one or more events for this interface. 

A failure or a reset of a PAM implementation may result in a loss of all prior event and interface registrations. The 
client application may need to confirm the continued registration of the notification interface and re-register if 
necessary. 

For security and privacy purposes, a registration for an event is allowed if and only if the supplied credentials during 
registration is sufficient to have allowed access to the information related to the event through one or more of the PAM 
interface methods. 
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«lnterface» 
IpPAMEventHandler 



isRegistered (clientlD : in TpPAMCIientID, authToken : in TpPAMCredential) : TpBoolean 

registerApplnterface (applnterface : in IpAppPAMEventHandlerRef, autin Token : in TpPAMCredential) : 
TpPAMCIientID 

registerForEvent (clientlD : in TpPAMCIientID, eventList : in TpPAMEventlnfoList, validFor : in TpDuration, 
authToken : in TpPAMCredential) : TpPAMEventID 

deregisterApplnterface (clientlD : in TpPAMCIientID, authToken : in TpPAMCredential) : void 

deregisterProm Event (eventID : in TpPAMEventID, authToken : in TpPAMCredential) : void 



8.3.3.1 Method isRegisteredQ 

Check if a client application interface is registered. 

Returns True if the registration ID is still valid, False otherwise. 

Parameters 

clientlD : in TpPAMCIientID 

Specifies the registration ID provided at registration. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.3.3.2 Method registerApplnterface() 

Register a client application's notification interface. 

Returns an ID returned by the service that uniquely identifies this registration. 

Parameters 

applnterface : in IpAppPAMEventHandlerRef 

Specifies the client notification interface. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 
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Returns 
TpPAMClientID 

Raises 

TpCommonExceptions , P_PAM_INVALID_CREDENTIAL 



8.3.3.3 Method registerForEvent() 

Register a client application's interest in one or more events. 

Returns an ID returned by the service that uniquely identifies this registration for the event. 

Parameters 

clientlD : in TpPAMClientID 

Specifies the registration ID provided at registration. 

event List : in TpPAMEventlnfoList 

Specifies the events of interest. 

validFor : in TpDuration 

Specifies the interval in milliseconds until which the subscription is held and notifications provided. A time interval of 
or negative values indicate a subscription that never expires until explicitly cancelled. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 
TpPAMEventID 

Raises 

TpCommonExceptions, P_PAM_NOT_REGISTERED, P_PAM_INVALID_CREDENTIAL 



8.3.3.4 Method deregisterApplnterfaceQ 

Unregister a client application's notification interface. 

All registrations for events for this client registration are also removed. 

Parameters 

clientID : in TpPAMClientID 

Specifies the registration ID provided at registration. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 
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Raises 

TpCommonExceptions, P_PAM_NOT_REGISTERED, P_PAM_INVALID_CREDENTIAL 



8.3.3.5 



Method deregisterFromEventO 



Unregister a client application's interest in an event. 

Parameters 

event ID : in TpPAMEventID 

Specifies a prior event registration ID. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_NOT_REGISTERED, P_PAM_INVALID_CREDENTIAL 



State Transition Diagrams 



There are no State Transition Diagrams for the Presence and Availability Management SCFs. 



10 PAIVI Service Properties 

The following table lists properties relevant to all the PAM SCFs. 



Property 


Type 


Description 


P_OBTAINABLE_INTERFACES 


STRING_SET 


The interfaces obtainable from the service. 


P_SUPPORTED_ATTRIBUTE_TAGS 


STRING_SET 


Lists the supported attribute tags defined by 
TpAttributeTaglnfo. 


P_SUPPORTED_SIMPLE_ATTRIBUTE 
_TYPES 


STRING_SET 


Lists the supported attribute types defined by 
TpSimpleAttributeTypelnfo. 


P_SUPPORTED_STRUCTURED_ATTRI 
BUTE_TYPES 


STRING_SET 


Lists the supported attribute types defined by 
TpStructuredAttributeType, e.g. P_org/csapi/TpAddress. 


P_SUPPORTED_XML 


STRING_SET 


Lists the supported versions of XML specifications such as 

XML schema specifications (e.g. through URLs), XML 

versions (e.g. version LO) or XPath (e.g. version LO). 



Implementations of the PAM APIs shall have the Service Properties set to the indicated values at a minimum: 



P_SUPPORTED_ATTRIBUTE_TAGS = { 

P_SIMPLE_TYPE 

} 

P_SUPPORTED_SIMPLE_ATTRIBUTE_TYPES 

P_STRING, 

P_FLOAT, 

P INT32 
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10.1 PAM Access Service 

Implementations of the PAM Access APIs for 3GPPshall have the Service Properties set to the indicated values: 

P_OBTAINABLE_INTERFACES = { 
P_PAM_IDENTITY_PRESENCE, 
P_PAM_AVAI LAB I L I T Y 



10.2 PAM Event Service 

PAM Event service has the following property in addition to the above. 



Property 


Type 


Description 


P_EVENT_TYPES 


INTEGER_SET 


The pre-defined event types that can be registered for 



11 



PAIVI Data Definitions 



All data types referenced in this document but not defined in this clause are common data definitions which may be 
found in 3GPP TS 29.198-2. 

11.1 Entity Address Definitions 

11.1.1 TpPAIVIFQName 

This is the same as TpURN and is used to name entities in PAM Access service. 

11.1.2 TpPAIVIFQNameLlst 

This is a Numbered List of Data Elements of type TpPAMFQName. 

1 1 .2 Attribute Data Definitions 
11.2.1 TpPAIVIAttribute 

This is a Sequence of Data Elements containing the attribute name, expiration time and value. This is derived 
from the common attribute type TpAttribute to add the expiration value for dynamic attributes. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


AttributeName 


TpString 


The name of the attribute. 


AttributeValue 


TpAttributeValue 


The typed value(s) for the attribute. 


Expiresin 


TpPAMTimelnterval 


The interval in milliseconds in which the attribute values are 

valid. A time interval of PAM_MAX_LONGINT indicates 

static attribute values that never expire. A time interval of or 

negative values indicate an expired value and the time for 

which it has expired. 



1 1 .2.2 TpPAIVIAttrlbuteLlst 



This is a Numbered List of Data Elements of type TpP AM Attribute. 



ETSI 



3GPP TS 29.198-14 version 6.3.1 Release 6 



82 



ETSI TS 129 198-14 V6.3.1 (2006-07) 



1 1 .2.3 TpPAMAttributeDef 



This is a Sequence of Data Elements containing the definition of an attribute. This definition constitutes the 
"schema" for an attribute and contains fields to define the type and behavior of a dynamic attribute. Each definition 
using these fields results in a TpPAMAttribute with the corresponding name and type and dynamic behavior as defined 
by the remaining fields. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Name 


TpString 


Name of attribute 


Type 


TpString 


Type of attribute. Valid values for Type must include at least 
TpString, Tplnt32 and TpFloat 


IsStatic 


TpBoolean 


True indicates that the attributes is always static and its values 

never expire. False indicates that the attribute can be dynamic 

and may contain values that expire. 


IsRevertOnExpiration 


TpBoolean 


True indicates that the attribute reverts to the default value on 

expiration. False indicates that the attribute will not reveil to the 

default value. 


DefaultValues 


TpAny 


An attribute is always initialized with this value. If the 

isRevertOnKxpiration attribute is set to true, a dynamic attribute 

that has expired while stored in a PAM implementation is reset 

to this value with the expiresin interval set to 

PAM_MAX_LONGINT. The default attribute value is 

interpreted based on the value of the attribute Type. 



1 1 .2.4 TpPAMAttributeDefList 



This is a Numbered List of Data Elements of type TpPAMAttributeDef 



1 1 .3 Presence Data Definitions 



11.3.1 TpPAIVICapability 



This defines the extensible communication capabilities. This data type is identical to a TpString, and is defined as a 
string of characters that specify the communication capabilities. The following strings are pre-defined. 



Character String Value 


Description 


P_PAM_VOICE 


Capability for voice calls 


P_PAM_SMS 


Capability for SMS 


P_PAM_IM 


Capability for Instant Messaging 


P_PAM_MMS 


Capability for Multi-media messaging 



11.3 



Tp 



This is 
a 



Numbered List of Data Elements of type TpPAMCapability. 

1 1 .3.3 TpPAIVIPresenceData 

This is a Sequence of Data Elements for a specific identity type Presentity pre-defined in PAM. Since 
multiple presence data records can be associated with an identity, each distinct record is uniquely named. 



Sequence Element Name 


Sequence Element Type 


Notes 


Name 


TpString 


Name of presence data 


PresenceAttributes 


TpPAMAttributeList 


Presence Attributes 
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1 1 .3.4 TpPAMPresenceDataList 

This is a Numbered List of Data Elements of type TpPAMPresenceData. 

1 1 .4 Pre-defined Presence type 
11.4.1 Presentity 

An identity type Presentity is pre-defined for all identities associated with the attribute PresenceProfile defined as: 



Attribute Definition Field 


Value 


Name 


PresenceProfile 


Type 


TpPAMPresenceData 


IsStatic 


False 


IsRevertOnExpiration 


False 


DefaultValues 


Null 



1 1 .5 Availability Data Definitions 
11.5.1 TpPAMAvailabilityProf lie 

This is a Sequence of Data Elements containing the list of attribute values as determined by the definition of 
the context for which the availability is provided. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


PrivacyCode 


TpPAMPrivacyCode 


Contains the privacy codes 


AvailabilityData 


TpPAMPresenceData 


Contains a list of presence attributes 



1 1 .5.2 TpPAMAvaliabliityProfiieLlst 

This is a Numbered List of Data Elements of type TpPAMAvailabilityProfile. 

1 1 .5.3 TpPAMPrivacyCode 

This data type is identical to a TpString, and is defined as a string of characters that specify the privacy code for 
availability profiles. These codes are just indications of the privacy expected by the service and not are meant to be 
enforced by the service. Other Network operator specific codes may also be used, but should be preceded by the string 
" S_". The following values are defined. 



Character String Value 


Description 


PAM_CP_ASKER_ONLY 


The profile is available to the asker only and should not be further transmitted 


PAM_CP_AUTHORI ZED 


The profile can be provided by the asker to authorized entities 


PAM_CP_UNLIMITED 


The profile can be distributed without hmits 



1 1 .6 Availability Context Data Definitions 

Availability is always queried for in a specific context on behalf of an asker. There is one context for communication 
pre-defined in this version of the specification. 



ETSI 



3GPP TS 29.198-14 version 6.3.1 Release 6 



84 



ETSI TS 129 198-14 V6.3.1 (2006-07) 



11.6.1 TpPAMContext 



This is a Sequence of Data Elements containing the data which defines the context in which an availability is 
queried and information about the asker that is requesting the data. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


ContextData 


TpPAMContextData 


Contains the context name and the hst of attributes that define the 

context. The attributes to be included for a given context are 

specified by the definition of the context. 


AskerData 


TpAttributeList 


Contains information about the asker of availabihty. The exact 

attributes in this hst are dependent on the apphcation. PAM 

reserves the attribute "name" with type TpPAMFQName to 

contain the identity of the asker if known. 



1 1 .6.2 TpPAMContextName 

This specifies the availability contexts. 



Name 


Value 


Description 


PAM_CONTEXT_ANY 





Denotes any known context 


PAM_CONTEXT_COMMUNICATION 


1 


Denotes a communication context 



1 1 .6.3 TpPAMContextData 

This is a tagged choice of data elements that specifies the optional data that may be required to define a 
particular context. 





Tag Element Type 






TpPAMContextName 






Tag Element Value 


Choice Element Type 


Choice Element Name 


PAM_CONTEXT_ANY 


None 


Undefined 


PAM_CONTEXT_COI«UN I CAT ION 


TpPAMCommunicationContext 


CommunicationContext 



1 1 .6.4 TpPAMCommunicationContext 



This is a Sequence of Data Elements containing the list of attribute values for defining a communication 
context. 



Sequence Element Name 


Sequence Element Type 


Notes 


CommunicationCapability 


TpPAMCapability 


Specifies the communication type for which the availability 
is requested 



1 1 .6.5 TpPAMContextList 

This is a Numbered List of Data Elements of type TpPAMContext. 
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1 1 .7 Credential data definitions 
11.7.1 TpPAIVICredential 

This is the same as TpOctetSet. This data is opaque to the appHcation and is implementation dependent. As this data is 
vaHd only in the context of a single session with the service and hence cannot be used across multiple services, there are 
no inter-operability issues here. The application simply uses the credential returned from the getAuthToken() method in 
all other methods that require the credentials. 

1 1 .8 Availability and Access Control Preference Data Definitions 

PAM allows several types of preferences to be specified. It includes an access control list specifying who is allowed to 
check for presence or subscribe to presence data for each identity. It also includes an interface for an application to 
register an interface to do access control checks and availability computations outside of the presence service. 

1 1 .8.1 IpAppPAMPreferenceCheckRef 

Defines a Reference to type IpAppPAMPreferenceCheck. 

1 1 .8.2 TpPAMAccessControlData 

This is a Sequence of Data Elements for access control data. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


DefaultPolicy 


TpPAMACLDefault 


Specifies whether the default poUcy is to allow or deny access 
for names not mentioned in the list 


AllowList 


TpPAMFQNameList 


Specifies a list of identities to be allowed access 


DenyList 


TpPAMFQNameList 


Specifies a list of identities to be denied access 



1 1 .8.3 TpPAMACLDefault 

Defines the two possible default policies for access control. 



Name 


Value 


Description 


PAM_ACCESS_ALLOW 





Allow access by default 


PAM_ACCESS_DENY 


1 


Deny access by default 



1 1 .8.4 TpPAMPreferenceOp 

This data type is identical to a TpString, and is defined as a string of characters that specify the operations to be 
performed with a preference. The following values are defined. 



Character String Value 


Description 


PAM_ACCESS_ADD 


Add the specified preference to the current preferences 


PAM_ACCESS_DELETE 


Delete the specified preference from the current preferences 


PAM_ACCESS_REPLACE 


Replace the current preferences with the specified preference 
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11.8.5 TpPAMPreferenceType 



This specifies the names of privacy and access control mechanisms supported by the service. 



Name 


Value 


Description 


PAM_ACCESS_LIST 





The control data contains additions or modifications to access 
control list of who is authorized to access the presence 
infomiation or subscribe to it. 


PAM_EXTERNAL_CONTROL 


1 


The access control and availability computations are done 
external to the presence service 



1 1 .8.6 TpPAMPreferenceData 

This is a tagged choice of data elements that specifies the preference data. The data depends on the type 
of preference being specified. 





Tag Element Type 






TpPAMPreferenceType 






Tag Element Value 


Choice Element Type 


Choice Element Name 


PAM_EXTERNAL_CONTROL 


IpAppPAMPreferenceCheckRef 


Ext ernalControl Inter face 



11.9 Time data definitions 
11.9.1 TpPAIVITImelnterval 

This is identical to Tplnt64. 

11.10 Pre-defined Entity Types and Attributes 

This version of the specification pre-defines one identity type called "Presentity". The following constant can be used to 
refer to this Identity Type. All identities in the PAM service are associated with this identity type. For example, the 
identityType parameter in IpIdentityPresence and IpEventHandler methods take this as the value. This is also used in 
the event registration data structure (e.g., TpPAMAVCEventData) in the IdentityType field. 



Character String Value 


Description 


P_P AM_P RESENT IT Y_TYPE 


The pre-defined identity type called Presentity. 



Every identity type in PAM can be defined with a set of attributes that are associated with all identities of that type. The 
following dynamic attributes are pre-defined as attributes of type TpPAMAttribute for the "Presentity" identity type and 
shall be supported as attributes of all identities in implementations of this service. These attributes are defined using 
TpP AM AttributeDef fields as follows. 
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AttributeName 


AttributeType 


IsStatic 


IsRevertOn 
Expiration 


DefaultValue 


Description 


P_SUBSCRIBER_STATUS 


P_STRING 


False 


False 


None 


Specifies the status of the 
subscriber 


P_NETWORK_STATUS 


P_STRING 


False 


False 


None 


Specifies the status of the 
network 


P COMMUNICATION MEAN 
S 


P org/csapi/pa 

m/TpPAMCap 

ability 


False 


False 


None 


Specifies the means of 

communication. The type is 

TpPAMCapabihty 


P_CONTACT_ADDRESS 


P_org/csapi/Tp 
Address 


False 


False 


None 


Address for communication 


P_SUBSCRIBER_PROVIDE 
D_LOCATION 


P_STRING 


False 


False 


None 


Location nformation provided 
by subscriber. Is optional. 


P_NETWORK_PROVIDED_L 
OCATION 


P_STRING 


False 


False 


None 


Location information provided 
by subscriber. Is optional. 


P_PRIORITY 


P_INT32 


False 


False 


None 


Priority for communication 


P_OTHER_INFO 


P_STRING 


False 


False 


None 


Additional information 



11.11 Interface name definitions 

This section defines the names to be used for obtaining interfaces from the corresponding service interfaces in each 
PAM SCF. 

11.11.1 TpPAIVIProvlslonlnglnterfaceName 

This data type is identical to a TpString, and is defined as a string of characters that identify the names of the PAM 
Provisioning interfaces that are to be supported by the OSA API. 



Character String Value 


Description 


P„PAM„IDENTITY_MANAGEMENT 


The name for the PAM Identity Management interface. 


P_PAM_AGENT_MANAGEMENT 


The name for the PAM Agent Management interface 


P_PAM_AGENT_ASSIGNMENT 


The name for the PAM Agent Assignment interface 


P_PAM_IDENTITY_TYPE_MANAGEMENT 


The name for the PAM Identity Type Management interface 


P_PAM_AGENT_TYPE_MANAGEMENT 


The name for the PAM Agent Type Management interface 


P_PAM_CAPABILITY_TYPE_MANAGEMENT 


The name for the PAM Capability Type Management interface 



11.11.2 TpPAIVIPresenceAvailabilitylnterfaceName 

This data type is identical to a TpString, and is defined as a string of characters that identify the names of the PAM 
Access interfaces that are to be supported by the OSA API. 



Character String Value 


Description 


P„PAM„IDENTITY_PRESENCE 


The name for the PAM Identity Presence interface. 


P_PAM_AGENT_PRESENCE 


The name for the PAM Agent Presence interface 


P„PAM_AVAILABILITY 


The name for the PAM Availability interface 



11.11.3 TpPAIVIEventlnterfaceName 

This data type is identical to a TpString, and is defined as a string of characters that identify the names of the PAM 
Event management interfaces that are to be supported by the OSA API. 



Character String Value 


Description 


P_PAM_EVENT_HANDLER 


The name for the Event Handler interface. 
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11.12 Event data definitions 

There are two sets of data structures used for events. One set is used by applications to provide information when 
registering for an event and the second set is used to supply information to the applications in the notifications when the 
events occur. 

11.12.1 IpAppPAIVIEventHandlerRef 

Defines a Reference to type IpAppPAMEventHandler. 

11.12.2 TpPAIVICIIentlD 

This is the same is Tplnt32 and is used to identify, uniquely within an implementation, registration of an application 
interface for notification of events. 



11.12.3 TpPAIVIEventID 



This is the same as TpAssignmentID and is used to identify, uniquely within an implementation, a registration for a 
specific event. 



11.12.4 TpPAIVIEventName 

This data type identifies the values that specify the event names. 



Name 


Value 


Description 


PAM_CE_IDENTITY_PRESENCE_SET 





Notify if the value of presence attributes of an identity is 
explicitly set 


PAM_CE_AVAILABILITY_CHANGED 


1 


Notify if the availabihty of an identity changes 


PAM_CE_WATCHERS_CHANGED 


2 


Notify if the cunent set of watchers change 


PAM_CE_IDENTITY_CREATED 


3 


Notify if a new identity has been created 


PAM_CE_IDENTITY_DELETED 


4 


Notify if an identity has been deleted 


PAM_CE_GROUP_MEMBERSHIP_CHANGED 


5 


Notify if the membership of a group changes 


PAM_CE_AGENT_CREATED 


6 


Notify if a new agent has been created 


PAM_CE_AGENT_DELETED 


7 


Notify if an agent has been deleted 


PAM_CE_AGENT_AS SIGNED 


8 


Notify if an agent is assigned to an identity 


PAM_CE_AGENT_UNAS S I GNED 


9 


Notify if an agent has been unassigned from an identity 


PAM_CE_CAPABILITY_CHANGED 


10 


Notify if the capability of an identity changes 


PAM_CE_AGENT_CAPABILITY_PRESENCE_SET 


11 


Notify if the value of presence attributes of an agent is 
explicitly set 


PAM_CE_AGENT_PRESENCE_SET 


12 


Notify if the value of presence attributes of an agent is 
explicitly set 



11.12.5 TpPAIVIEventNameLlst 

This is a Numbered List of Data Elements of type TpPAMEventName. 

Each event is defined by the data that applications must provide during registration using TpPAMEventlnfo and data 
that is provided to the apphcation during notification of such events using TpPAMNotificationlnfo. 
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11.12.6 TpPAMEventlnfo 



This is a tagged choice of data elements that specifies the event data provided by applications while 
registering. 





Tag Element Type 






TpPAMEventName 






Tag Element Value 


Choice Element Type 


Choice Element Name 


PAM_CE_IDENTITY_PRESENCE_SET 


TpPAMIPSEventData 


IdentityPresenceSet 


PAM_CE_AVAILABILITY_CHANGED 


TpPAMAVCEventData 


Aval lability Changed 


PAM_CE_WATCHERS_CHANGED 


TpPAMWCEventData 


Watchers Changed 


PAM_CE_IDENTITY_CREATED 


TpPAMICEventData 


Identity Created 


PAM_CE_IDENTITY_DELETED 


TpPAMIDEventData 


IdentityDeleted 


PAM_CE_GROUP_MEMBERSHIP_CHANGED 


TpPAMGMCEventData 


GroupMembershipChanged 


PAM_CE_AGENT_CREATED 


TpPAMACEventData 


AgentCreated 


PAM_CE_AGENT_DELETED 


TpPAMADEventData 


AgentDeleted 


PAM_CE_AGENT_AS SIGNED 


TpPAMAAE vent Data 


Agent As signed 


PAM_CE_AGENT_UNAS SIGNED 


TpPAMAUEventData 


Agent Unas signed 


PAM_CE_CAPABILITY_CHANGED 


TpPAMCCEventData 


Capability Changed 


PAM_CE_AGENT_CAPABILITY_PRESENCE_SET 


TpPAMACP SEventData 


AgentCapabilityPresenceSet 


PAM_CE_AGENT_PRESENCE_SET 


TpPAMAPSEventData 


AgentPresenceSet 



11.12.7 TpPAMEventlnfoList 

This is a Numbered List of Data Elements of type TpPAMEventlnfo. 

11.12.8 TpPAMNotificationlnfo 

This is a tagged choice of data elements that specifies the notification data provided to the applications 
for each event. 





Tag Element Type 






TpPAMEventName 






Tag Element Value 


Choice Element Type 


Choice Element Name 


PAM_CE_IDENTITY_PRESENCE_SET 


TpPAMIPSNotif icationData 


IdentityPresenceSetNotify 


PAM_CE_AVAI LAB I L I T Y_CHANGED 


TpPAMAVCNotificationData 


AvailabilityChangedNotif y 


PAM_CE_WATCHERS_CHANGED 


TpPAMWCNot if icationData 


Watcher sChangedNotify 


PAM_CE_IDENTITY_CREATED 


TpPAMICNot if icationData 


IdentityCreatedNotify 


PAM_CE_IDENTITY_DELETED 


TpPAMIDNot if icationData 


IdentityDeletedNotify 


PAM_CE_GROUP_MEMBERSHIP_CHANGED 


TpPAMGMCNot if icationData 


GroupMembershipChangedNotify 


PAM_CE_AGENT_CREATED 


TpPAMACNot if icationData 


Agent Cr eat edNotify 


PAM_CE_AGENT_DELETED 


TpPAMADNot if icationData 


Agent DeletedNotify 


PAM_CE_AGENT_AS SIGNED 


TpPAMAANot if icationData 


AgentAssignedNotify 


PAM_CE_AGENT_UNAS SIGNED 


TpPAMAUNot if icationData 


Agent Una ssignedNotify 


PAM_CE_CAPAB I L I T Y_CHANGED 


TpPAMCCNot if icationData 


CapabilityChangedNotif y 


PAM_CE_AGENT_CAPABILITY_PRESENC 
E_SET 


TpPAMACPSNot if icationData 


AgentCapabilityPresenceSetNotif y 


PAM_CE_AGENT_PRESENCE_SET 


TpPAMAPSNot if icationData 


AgentPresenceSetNotify 
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11.12.9 TpPAMNotificationlnfoList 

This is a Numbered List of Data Elements of type TpPAMNotificationlnfo. 

1 1 .1 2.1 PAM_CEJDENTITY_CREATED 

Notify if a new identity has been created. Notifications for creation of muhiple identities are bunched into a single 
notification whenever possible. A notification of this event is NOT sent for new association of types with an existing 
identity. 

11.12.10.1 TpPAMICEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to identity creations. The event 
is registered for changes in any agents of the named type. If no identity types are named, then the event is registered for 
all identity types. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


IdentityType 


TpStringList 


Specifies the type of the identities for which this notification 

is requested. Can be an empty aiTay if notification required 

for identities of any type. 



11.12.10.2 TpPAMICNotificationData 



This is a Sequence of Data Elements to specify the data that is provided in the notifications for identity 
creation events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identities 


TpPAMFQNameList 


Contains the names of the identities that have been created. 



11.12.11 PAM_CEJDENTITY_DELETED 

Notify if an identity has been deleted. Notifications for deletion of multiple identities are bunched into a single 
notification whenever possible. A notification of this event is NOT sent for removing association of types with an 
existing identity. 

11.12.11.1 TpPAMIDEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to identity deletions. The event 
is registered for changes in any of the named identities. If no identities are named, then the event is registered for all 
agents. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


IdentityName 


TpPAMFQNameList 


Specifies the name of the identity whose deletion is to be 
notified. Can be an empty array 


IdentityType 


TpStringList 


Specifies the type of the identity for which this notification is 

requested if identityName is an empty an'ay. Can be an empty 

array if notification required for identities of any type 
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1 1 .1 2.1 1 .2 TpPAMIDNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for identity 
deletion events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identities 


TpPAMFQNameList 


Contains the names of the identities that have been deleted. 



11.12.12PAM_CE_GROUP_MEMBERSHIP_CHANGED 

Notify if the membership of a group changes. Notifications for changes to multiple groups are bunched into a single 
notification whenever possible. 

11.12.12.1 TpPAMGMCEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to group membership changes. 
The event is registered for changes in any of the named groups. If no groups are named, then the event is registered for 
all groups. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


GroupName 


TpPAMFQNameList 


Specifies the name of the group for which the change is to be 

notified. Can be an empty array if notifications are required 

for any group. 


GroupType 


TpStringList 


Specifies the type of the group for which this notification is 

requested if the groupName is specified as an empty array. 

Can be an empty array if notification required for groups of 

any type. 



1 1 .1 2.1 2.2 TpPAMGMCNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for group 
membership changes. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Groups 


TpPAMFQNameList 


Contains the names of the groups that have been changed. 



11.12.13PAM_CE_AGENT_CREATED 

Notify if a new agent has been created. Notifications for creation of multiple agents are bunched into a single 
notification whenever possible. The notification for this event is NOT sent for new associations of types with agents. 

11.12.13.1 TpPAMACEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent creations. The event is 
registered for changes in any agents of the named type. If no agent types are named, then the event is registered for all 
agent types. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


AgentType 


TpStringList 


Specifies the type of the agents for which this notification is 

requested. Can be an empty array if notification required for 

agents of any type 
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1 1 .1 2.1 3.2 TpPAMACNotificationData 



This is a Sequence of Data Elements to specify the data that is provided in the notifications for agent creation 
events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Agents 


TpPAMFQNameList 


Contains the names of the agents that have been created. 



11.12.14PAM_CE_AGENT_DELETED 

Notify if an agent has been deleted. Notifications for deletion of multiple agents are bunched into a single notification 
whenever possible. This event notification is NOT sent for disassociating a type from an agent. 

11.12.14.1 TpPAMADEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent deletions. The event is 
registered for changes in any of the named agents. If no agents are named, then the event is registered for all agents. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


AgentName 


TpPAMFQNameList 


Specifies the name of the agent whose deletion is to be 
notified. Can be an empty array 


AgentType 


TpStringList 


Specifies the type of the agent for which this notification is 

requested if agentName is an empty array. Can be an empty 

array if notification required for agents of any type 



11.12.14.2 TpPAMADNotificationData 



This is a Sequence of Data Elements to specify the data that is provided in the notifications for agent deletion 
events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Agents 


TpPAMFQNameList 


Contains the names of the agents that have been deleted. 



11.12.15PAM_CE_AGENT_ASSIGNED 

Notify if an agent is assigned to an identity. 
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11.12.15.1 TpPAMAAEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent assignments from an 
identity. The event is registered for changes in any of the named agents. If no agents are named, then the event is 
registered for any agent. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


IdentityName 


TpPAMFQNameList 


Specifies the name of the identity for which the assignment is 

to be notified. Can be an empty array if notification is 

required for any identity instance. 


Identity Type 


TpStringList 


Specifies the type of the identity for which this notification is 

requested if the identityName is specified as an empty array. 

Can be an empty array if notification required for identities of 

any type. 


AgentName 


TpPAMFQNameList 


Specifies the name of the agent whose assignment is to be 
notified. Can be an empty array 


AgentType 


TpStringList 


Specifies the type of the agent for which this notification is 

requested if agentName is an empty array. Can be an empty 

array if notification required for agents of any type 



1 1 .1 2.1 5.2 TpPAMAANotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for agent 
assignment events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity 


TpPAMFQName 


Contains the name of the identity to whom an agent has been 
assigned. 


Agent 


TpPAMFQName 


Contains the name of the agent that has been assigned. 



11 .1 2.1 6 PAM_CE_AGENT_UNASSIGNED 

Notify if an agent has been unassigned from an identity. 

11.12.16.1 TpPAMAUEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent unassignments from an 
identity. The event is registered for changes in any of the named agents. If no agents are named, then the event is 
registered for all assigned agents. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


IdentityName 


TpPAMFQNameList 


Specifies the name of the identity for which the unassignment 

is to be notified. Can be an empty array if notification is 

required for any identity instance. 


IdentityType 


TpStringList 


Specifies the type of the identity for which this notification is 

requested if the identityName is specified as an empty array. 

Can be an empty array if notification required for identities of 

any type. 


AgentName 


TpPAMFQNameList 


Specifies the name of the agent whose unassignment is to be 
notified. Can be an empty array. 


AgentType 


TpStringList 


Specifies the type of the agent for which this notification is 

requested if agentName is an empty array. Can be an empty 

array if notification required for agents of any type. 
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1 1 .1 2.1 6.2 TpPAMAUNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for agent 
unassignment events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity 


TpPAMFQName 


Contains the name of the identity from whom an agent has 
been unassigned. 


Agent 


TpPAMFQName 


Contains the name of the agent that has been unassigned. 



11.12.17PAM_CE_CAPABILITY_CHANGED 

Notify if the capabiHty of an identity changes. 

11.12.17.1 TpPAMCCEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to identity capabiHty changed 
events. The event is registered for changes in any of the named capabiHties. If no capabiHties are named, then the event 
is registered for all capabilities. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


IdentityName 


TpPAMFQNameList 


Specifies the name of the identity for which the capability 

change is to be notified. Can be an empty array if notification 

is required for any identity instance. 


IdentityType 


TpStringList 


Specifies the type of the identity for which this notification is 

requested if the identityName is specified as an empty array. 

Can be an empty array if notification required for identities of 

any type. 


Capabilities 


TpPAMCapabilityList 


Specifies the capabilities of interest. Can be an empty array if 
notifications are required for any capability. 



1 1 .1 2.1 7.2 TpPAMCCNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for capability 
change events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity 


TpPAMFQName 


Contains the name of the identity whose capability has 
changed. 


Capabilities 


TpPAMCapabilityList 


Contains the capabilities that have changed (i.e., added or 
removed). 



11.12.18PAM_CE_AGENT_CAPABILITY_PRESENCE_SET 

Notify if the value of capability presence attributes of an agent is set. Expiration of the dynamic attributes does not 
trigger this notification. 
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11.12.18.1 TpPAM ACPSEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent capability presence set 
events. The event is registered for changes in any of the named attributes. If no attributes are named, then the event is 
registered for all attributes in the presence information. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


AgentName 


TpPAMFQNameList 


Specifies the name of the agent for which the capability 

presence change is to be notified. Can be an empty array if 

notification is required for any agent instance. 


AgentType 


TpStringList 


Specifies the type of the agent for which this notification is 

requested if the agentName is specified as an empty array. 

Can be an empty array if notification required for agents of 

any type. 


Capabilities 


TpPAMCapabilityList 


Specifies the capabilities of interest. Can be an empty array if 
notifications are required for any capability. 


AttributeNames 


TpStringList 


Specifies attributes of interest. Can be an empty array 


Report ingPeriod 


TpPAMTimelnterval 


Specifies the interval for periodic reporting (regardless of 

change). If -1, the event notification happens only on a 

change. If 0, there is a single immediate notification. 



1 1 .1 2.1 8.2 TpPAMACPSNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for capability 
presence set events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Agent 


TpPAMFQName 


Contains the name of the agent whose capability presence has 
changed 


Capability 


TpPAMCapability 


Specifies the capability for which the presence has changed. 


AttributeNames 


TpStringList 


Contains the attribute names that have changed in value 



11.12.19PAM_CE_AGENT_PRESENCE_SET 

Notify if the value of presence attributes of an agent is set. Expiration of the dynamic attributes does not trigger this 
notification. 

11.12.19.1 TpPAMAPSEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent presence set events. 
The event is registered for changes in any of the named attributes. If no attributes are named, then the event is registered 
for all attributes in the presence information. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


AgentName 


TpPAMFQNameList 


Specifies the name of the agent for which the assignment is to 

be notified. Can be an empty array if notification is required 

for any agent instance. 


AgentType 


TpStringList 


specifies the type of the agent for which this notification is 

requested if the agentName is specified as an empty array. 

Can be an empty array if notification required for agents of 

any type. 


AttributeNames 


TpStringList 


Specifies attributes of interest. Can be an empty array. 


Report ingPeriod 


TpPAMTimelnterval 


Specifies the interval for periodic reporting (regardless of 

change). If -1, the event notification happens only on a 

change. If 0, there is a single immediate notification. 
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11.12.19.2 TpPAMAPSNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for agent 
presence set events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Agent 


TpPAMFQName 


Contains the name of the agent whose capabihty has changed 


AttributeNames 


TpStringList 


Contains the attribute names that have changed in value 



11.1 2.20 PAM_CEJDENTITY_PRESENCE_SET 

Notify if the value of presence attributes of an identity is set. Expiration of the dynamic attributes does not trigger this 
notification. 

11.12.20.1 TpPAMIPSEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to identity presence set events. 
The event is registered for changes in any of the named attributes. If no attributes are named, then the event is registered 
for all attributes in the presence information. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


IdentityName 


TpPAMFQNameList 


Specifies the name of the identity for which the assignment is 

to be notified. Can be an empty array if notification is 

required for any identity instance. 


IdentityType 


TpStringList 


specifies the type of the identity for which this notification is 

requested if the identityName is specified as an empty array. 

Can be an empty array if notification required for identities of 

any type. 


AttributeNames 


TpStringList 


Specifies attributes of interest. Can be an empty an'ay. 


Report ingPeriod 


TpPAMTimelnterval 


Specifies the interval for periodic reporting (regardless of 

change). If -1, the event notification happens only on a 

change. If 0, there is a single immediate notification even if 

there is no change. For all other values, there is a periodic 

notification at the specified time interval regardless of 

change. 



1 1 .1 2.20.2 TpPAM I PS Notification Data 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for identity 
presence set events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity 


TpPAMFQName 


Contains the name of the identity whose capability has 
changed 


Attributes 


TpPAMPresenceDataList 


Contains the attributes that have changed in value 



11.12.21 PAM_CE_AVAILABILITY_CHANGED 

Notify if the availability of an identity changes. The event is registered for changes in any of the named attributes. If no 
attributes are named, then the event is registered for all attributes in the presence information. 
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11.12.21.1 TpPAMAVCEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to availability changed events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


IdentityName 


TpPAMFQNameList 


Specifies the name of the identity for which the assignment is 

to be notified. Can be an empty array if notification is 

required for any identity instance. 


IdentityType 


TpStringList 


specifies the type of the identity for which this notification is 

requested if the identityName is specified as an empty array. 

Can be an empty aiTay if notification required for identities of 

any type. 


PAMContext 


TpPAMContextList 


Specifies the context in which the availability is to be 
monitored. Cannot be an empty array 


AttributeNames 


TpStringList 


Specifies attributes of interest. Can be an empty array 


Report ingPeriod 


TpPAMTimelnterval 


Specifies the interval for periodic reporting (regardless of 

change). If -1, the event notification happens only on a 

change. If 0, there is a single immediate notification even if 

there is no change. For all other values, there is a periodic 

notification at the specified time interval regardless of 

change. 



1 1 .1 2.21 .2 TpPAMAVCNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for availability 
changed events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity 


TpPAMFQName 


Contains the name of the identity whose capability has 
changed 


Availability 


TpPAMAvailabilityProf 
ileList 


Contains the availability information that has changed 



1 1 .1 2.22 PAM_CE_WATCHERS_CHANGED 

Notify if list of watchers for any event changed. 

1 1 . 1 2.22. 1 TpPAMWCEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to watchers changed events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Events 


TpPAMEventNameList 


Specifies the hst of events for which the watchers are to be 

monitored. Can be an empty array if notification is required 

for watchers to any event 


IdentityName 


TpPAMFQNameList 


Specifies the name of an identity for whom the change in 

watchers is to be notified. Can be an empty array if 

notification is required for any identity instance. 


IdentityType 


TpStringList 


specifies the type of the identity for which this notification is 

requested if the identityName is specified as an empty array. 

Can be an empty array if notification required for identities of 

any type. 


Report ingPeriod 


TpPAMTimelnterval 


Specifies the interval for periodic reporting (regardless of 

change). If -1, the event notification happens only on a 

change. If 0, there is a single immediate notification even if 

there is no change. For all other values, there is a periodic 

notification at the specified time interval regardless of 

change. 
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1 1 .1 2.22.2 TpPAMWCNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for watchers 
changed events. 



Sequence Element Name 


Sequence Element Type 


Notes 


Event 


TpPAMEventName 


Contains the name of the event for which the watchers 
changed 


ChangeType 


TpPAMwat Cher ChangeType 


Specifies whether the Usted watchers were added or 
deleted 


Identity 


TpPAMFQName 


Contains the name of the identity whose capability has 
changed 


Watchers 


TpPAMFQNameList 


Contains the list of watchers involved in the change 



11 . 1 2.22.3 TpPAMwatcherChangeType 

This specifies the values representing the type of change that occurred to the Hst of watchers. 



Name 


Value 


Description 


PAM_WATCHERS_PERIODIC 





Periodic reporting, not necessarily a change. 


PAM_WATCHERS_ADDED 


1 


Watchers added to the hst 


PAM_WATCHERS_DELETED 


2 


Watchers deleted from the hst 



11.13 Error Types 
11.13.1 TpPAMErrorCause 

This defines the types of errors reported by PAM. 



Name 


Value 


Description 


P_PAM_CAUSE_UNDEFINED 





Undefined. 


P_PAM_CAUSE_INVALID_ADDRESS 


1 


The request cannot be handled because the address specified is not vahd. 


P_PAM_CAUSE_SYSTEM_FAILURE 


2 


System failure. 

The request cannot be handled because of a general problem in the service 

or in the underlying network. 


P_PAM_CAUSE_INFO_UNAVAILABLE 


3 


The information is currently not available. 


P_PAM_CAUSE_EVENT_REGISTRATION_CANCELLED 


4 


The registration for the event has been cancelled by the service. 



11.13.2 TpPAMErrorlnfo 



This is a Sequence of Data Elements to specify the error notification data. 



Sequence Element Name 


Sequence Element 
Type 


Description 


Cause 


TpPAMErrorCause 


Contains information about the reason for the en'or 


ErrorData 


TpPAMNotificationlnfo 


Contains information relevant to each error such as the 

identity for which the eiTor exists and/or the attributes for 

which the eiTor exists 
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12 Presence and Availability Management Exception 
Classes 

The following are the list of exception classes which are used in this interface of the API. 



Name 


Description 


P_PAM_AGENT_EXISTS 




ndicates that an Agent with the agentName already exists 


P_PAM_ALIAS_EXISTS 




ndicates that the specified aUas is already associated to the Identity 


P_PAM_ALIAS_NOT_UNIQUE 




ndicates that the alias has already been assigned to another identity 


P_PAM_ATTRIBUTE_EXISTS 




ndicates that at least one of the named attributes already exists 


P_PAM_D I SAS SOC I ATED_T YPE 




ndicates that one of the specified types is not associated with the named identity/agent 


P_PAM_IDENTITY_EXISTS 




ndicates that the specified Identity already exists 


P_PAM_INVALID_CREDENTIAL 




ndicates that the credential presented is not recognized or insufficient for the operation 


P_PAM_IS_CYCLIC 




ndicates that the requested operation will create cyclic relationship 


P_PAM_MEMBER_EX I ST S 




ndicates that the specified member is already in the group 


P_PAM_NO_CAP ABILITY 




ndicates that a supplied capability is not a capabihty of the requested agent. No attributes are affected 


P_PAM_NOT_MEMBER 




ndicates that the specified member is not member of the group 


P_PAM_NOT_REGISTERED 




ndicates that the interface was not previously registered 


P__PAM_NOT_SUPPORTED 




mplementation dependent status that indicates that this method is not supported by the implementation 


P_PAM_TYPE_ASSOCIATED 




ndicates that a named type has already been associated with the identity/agent 


P_PAM_TYPE_EXISTS 




ndicates that the named type already exists 


P_PAM_UNASSIGNED_ALIAS 




ndicates that the specified ahas was not an alias of the named identity 


P_PAM_UNAVAILABLE_INTERFACE 




ndicates that the specified interface does not exist or is unavailable 


P_PAM_UNKNOWN_AGENT 




ndicates that the Agent with the specified name does not exist 


P_PAM_UNKNOWN_ALIAS 




ndicates that the Alias with the specified name does not exist 


P_PAM_UNKNOWN_ASSIGNMENT 




ndicates that no assignment exists for this identity and agent 


P_PAM_UNKNOWN_ATTRIBUTE 




ndicates that at least one of the specified attributes has not been defined or has not been associated with 
he specified object 


P_PAM_UNKNOWN_ATTRIBUTES 




ndicates that the specified attribute list contains attributes not part of the named object 


P_PAM_UNKNOWN_CAPAB I L I T Y 




ndicates that a supplied capability is not a capability of the requested agent, or has not been defined. No 
attributes are affected 


P_PAM_UNKNOWN_GROUP 




ndicates that the specified group identity does not exist 


P_PAM_UNKNOWN_IDENTITY 




ndicates that the specified identity does not exist 


P_PAM_UNKNOWN_MEMBER 




ndicates that the specified member identity does not exist 


P_PAM_UNKNOWN_TYPE 




ndicates that the named type does not exist / indicates that the named identity/agent has not been 
associated with the named type / indicates that a specified type name has not been defined as an agent 
ype 



Each exception class contains the following structure. 



Structure Element Name 


Structure Element Type 


Structure Element Description 


Extrainf ormation 


TpString 


Carries extra information to help identify the source of the 
exception, e.g. a parameter name 
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Annex A (normative): 

OMG IDL Description of Presence and Availability 

Management SCF 

The OMG IDL representation of this interface specification is contained in text files (pam_interfaces, pam_data.idl) 
contained in archive 2919814V630IDL.ZIP which accompanies the present document. 
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Annex B (informative): 

W3C WSDL Description of the Presence and Availability 

Management SCFs 

The W3C WSDL representation of this interface specification is contained in zip file 2919814V630WSDL.ZIP, which 
accompanies the present document. 
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Annex C (informative): 

Java™ API Description of the Presence and Availability 

Management SCFs 

The JavaT*^ API realisation of this interface specification is produced in accordance with the JavaT"^ ReaHsation rules 
defined in Part 1 of this specification series. These rules aim to deliver for Java''^, a developer API, provided as a 
realisation, supporting a Java^*^ API that represents the UML specifications. The rules support the production of both 
J2SE'''M and J2EE'"'^ versions of the API from the common UML specifications. 

The J2SET'^ representation of this interface specification is provided as Java^"^ Code, contained in archive 
2919814V630J2SE.ZIP that accompanies the present document. 

The J2EE"^ representation of this interface specification is provided as Java'"^ Code, contained in archive 
2919814V630J2EE.ZIP that accompanies the present document. 
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Annex D (informative): 

Description of Presence and Availability Management for 

3GPP2 cdma2000 networks 

This annex is intended to define the OSA API Stage 3 interface definitions and it provides the complete OSA 
specifications. It is an extension of OSA API specifications capabilities to enable operation in cdma2000 systems 
environment. They are in alignment with 3GPP2 Stage 1 requirements and Stage 2 architecture defined in 

[1] 3GPP2 P.SOOOl-B: "Wireless IP Network Standard", Version 1.0, September 2000; 

[2] 3GPP2 S.R0037-0: "IP Network Architecture Model for cdma2000 Spread Spectrum Systems", 

Version 2.0, May 14, 2002; 

[3] 3GPP2 X.S0013: "All-IP Core Network Multimedia Domain", December 2003. 

These requirements are expressed as additions to and/or exclusions from the 3GPP Release 6 specification. The 
information given here is to be used by developers in 3GPP2 cdma2000 network architecture to interpret the 3GPP 
OSA specifications. 



D.1 General Exceptions 



The term UMTS is not applicable for the cdma2000 family of standards. Nevertheless these terms are used (3GPP TR 
21.905) mostly in the broader sense of "3G Wireless System". If not stated otherwise there are no additions or 
exclusions required. 

CAMEL and CAP mappings are not applicable for cdma2000 systems. 



D.2 Specific Exceptions 
D.2.1 Clause 1: Scope 

There are no additions or exclusions. 

D.2.2 Clause 2: References 

Normative references on 3GPP TS 23.078 and on 3GPP TS 29.078 are not applicable for cdma2000 systems. 

D.2. 3 Clause 3: Definitions and abbreviations 

There are no additions or exclusions. 

D.2. 4 Clause 4: Presence and Availability Management SCF 

There are no additions or exclusions. 

D.2. 5 Clause 5: Sequence Diagrams 

There are no additions or exclusions. 
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D.2.6 Clause 6 Class Diagrams 

There are no additions or exclusions. 

D.2.7 Clause 7: The Service Interface Specifications 

There are no additions or exclusions. 

D.2.8 Clause 8: Presence and Availability Management Interface 
Classes 

There are no additions or exclusions. 

D.2.9 Clause 9: State Transition Diagrams 

There are no additions or exclusions. 

D.2.10 Clause 10: PAM Service Properties 

There are no additions or exclusions. 

D.2.1 1 Clause 1 1 : PAM Data Definitions 

There are no additions or exclusions. 

D.2.1 2 Clause 12: Presence and Availability Management 
Exception Classes 

There are no additions or exclusions. 

D.2.1 3 Annex A (normative) :OMG IDL Description of Presence and 
Availability Management SCF 

There are no additions or exclusions. 

D.2.1 4 Annex C (informative): Java™ API Description of Presence 
and Availability Management SCF 

There are no additions or exclusions. 
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Annex D (informative): 
Change history 



Change history 


Date 


TSG# 


TSG Doc. 


CR 


Rev 


Subject/Comment 


Old 


New 


April 2002 


-- 


-- 


- 


- 


Draft v1 00 submitted to TSG CN email list for Information 




1.0.0 


June 2002 


CN 16 


NP-020196 


- 


- 


Draft v200 submitted to TSG CN#1 6 for Approval 


2.0.0 


5.0.0 


Sep 2002 


CN 17 


NP-020440 


0001 


- 


Add text to clarify requirements on support of methods 


5.0.0 


5.1.0 


Sep 2002 


CN 17 


NP-020440 


0002 


- 


Remove declaration of unused datatype TpPAMTime 


5.0.0 


5.1.0 


Sep 2002 


CN_17 


NP-020395 


0003 


- 


Add text to clarify relationship between 3GPP and ETSI/Parlay OSA 
specifications 


5.0.0 


5.1.0 


Jun 2003 


CN 20 


NP-030245 


0004 


- 


Make TpPAMCapability extensible by changing its type to TpString 


5.1.0 


5.2.0 


Jun 2003 


CN 20 


NP-030240 


0005 


- 


Change the type of TpPAMFQName to TpURN 


5.1.0 


5.2.0 


Jun 2003 


CN_20 


NP-030245 


0006 


- 


Clarifiy use of askerData parameter to getAuthToken method in each 
PAM SCF 


5.1.0 


5.2.0 


Jun 2003 


CN 20 


NP-030245 


0007 


- 


Add authToken parameter to computeAvailability method 


5.1.0 


5.2.0 


Jun 2003 


CN_20 


NP-030245 


0008 


- 


Replace use of IplnterfaceRef in PAM with actual application 
interfaces 


5.1.0 


5.2.0 


Jun 2003 


CN 20 


NP-030245 


0009 


- 


Add expiration time for PAM event registrations 


5.1.0 


5.2.0 


Jun 2003 


CN 20 


NP-030245 


0010 


- 


Send subscription notification cancellation to watchers 


5.1.0 


5.2.0 


Jun 2003 


CN 20 


NP-030241 


0011 


- 


Change PAM Presence and Availability SCF name to PAM Access 


5.1.0 


5.2.0 


Jun 2003 


CN 20 


NP-030245 


0012 


- 


Move Access Control Mechanism to Manager Interface 


5.1.0 


5.2.0 


Sep 2003 


CN 21 


NP-030352 


0013 


- 


Correction to Java Realisation Annex 


5.2.0 


5.3.0 


Dec 2003 


CN_22 


NP-030548 


0017 


- 


Correction of description of TpAttributeType to adequately support 
possible types - Align with 29.1 98-02 


5.3.0 


5.4.0 


Dec 2003 


CN_22 


NP-030548 


0018 


- 


Correction of definitin of TpPAMAttribute and addition of Service 
Properties to publish supported attribute types - Align with 29.198-02 


5.3.0 


5.4.0 


Dec 2003 


CN 22 


NP-030553 


0014 


- 


Add OSA API support for 3GPP2 networks 


5.4.0 


6.0.0 


Dec 2003 


CN_22 


NP-030557 


0015 


- 


Include Provisioning SCF in Presence Service - Align with SAI's 
22.141 


5.4.0 


6.0.0 


Dec 2003 


CN_22 


NP-030557 


0016 


- 


Add methods to activate/deactivate PAM services for users - Align 
with SAI's 22.141 


5.4.0 


6.0.0 


Feb 2004 


— 


— 


— 


— 


Added Java code attachment 2919814J2EE.zip; which was delivered 
late by outside developers. See Annex B. 


6.0.0 


6.0.1 


Jun 2004 


CN 24 


NP-040272 


0020 


- 


Correction of introduction of PAM Provisioning Interfaces 


6.0.1 


6.1.0 


Sep 2004 


CN 25 


NP-040355 


0023 


- 


Correct J2EE source 


6.1.0 


6.2.0 


Sep 2004 


CN 25 


NP-040358 


0024 


- 


Support High Availability at API Level 


6.1.0 


6.2.0 


Dec 2004 


-- 


- 


- 


- 


OSA Stage 1 & 2 References clean-up 


6.2.0 


6.2.1 


Dec 2004 


-- 


- 


- 


- 


Adds code attachments 


6.2.1 


6.2.2 


Jun 2006 


CT 32 


CP-060194 


0025 


- 


Submission of OSA API SCFs description in W3C WSDL 


6.2.2 


6.3.0 


Jul 2006 


-- 


- 


- 


- 


Added missing code attachments 


6.3.0 


6.3.1 
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